@camstack/addon-import-alexa 0.2.177 → 0.2.178

package/dist/addon.mjs

@@ -6033,7 +6033,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../types/dist/sleep-_4vKNWxb.mjs
+//#region ../types/dist/sleep-B-vp7x15.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -9764,6 +9764,7 @@ var CAP_NAMES = Object.freeze([
 	"device-status",
 	"dishwasher",
 	"display-palette",
+	"do-not-disturb",
 	"doorbell",
 	"embedding-encoder",
 	"enum-sensor",
@@ -10523,6 +10524,10 @@ Object.freeze({
 			"valueType": "string"
 		}
 	],
+	"do-not-disturb": [{
+		"path": "enabled",
+		"valueType": "boolean"
+	}],
 	"doorbell": [{
 		"path": "lastPressedAt",
 		"valueType": "number"
@@ -20062,6 +20067,33 @@ var APPLIANCE_CAP_VOCABULARY = {
 			}
 		]
 	},
+	"do-not-disturb": {
+		scope: "device",
+		noun: t("Do not disturb", "Non disturbare"),
+		actions: [{
+			id: "dnd.on",
+			method: "setEnabled",
+			label: t("Do not disturb on", "Attiva Non disturbare"),
+			phrase: t("Turn on Do not disturb on {device}", "Attiva Non disturbare su {device}"),
+			icon: "bell-off",
+			args: { enabled: true }
+		}, {
+			id: "dnd.off",
+			method: "setEnabled",
+			label: t("Do not disturb off", "Disattiva Non disturbare"),
+			phrase: t("Turn off Do not disturb on {device}", "Disattiva Non disturbare su {device}"),
+			icon: "bell",
+			args: { enabled: false }
+		}],
+		state: [{
+			kind: "boolean",
+			field: "enabled",
+			label: t("Do not disturb", "Non disturbare"),
+			whenTrue: t("When Do not disturb turns on on {device}", "Quando {device} attiva Non disturbare"),
+			whenFalse: t("When Do not disturb turns off on {device}", "Quando {device} disattiva Non disturbare"),
+			icon: "bell-off"
+		}]
+	},
 	update: {
 		scope: "device",
 		noun: t("Firmware update", "Aggiornamento firmware"),
@@ -42178,14 +42210,16 @@ var DeviceIsLeafSchema = object({
 });
 /**
 * True when the camera currently has a PARKED object matching `subjects` in at
-* least one of `zones`. Reads the zone-analytics snapshot through the same
+* least one of `zones` (`minCount` of them, default one). Reads the zone-analytics snapshot through the same
 * mirror as every other state leaf, so a dropped event never decides it (D49).
 */
 var StationaryPresentLeafSchema = object({
 	kind: literal("stationary-present"),
 	deviceId: number$1().int().nonnegative(),
 	subjects: array(StationarySubjectSchema).min(1).optional(),
-	zones: array(string().min(1)).min(1).optional()
+	zones: array(string().min(1)).min(1).optional(),
+	/** How many matching parked objects must be there; absent means one. */
+	minCount: number$1().int().positive().optional()
 });
 /**
 * The escape hatch: the bounded expression engine over named device bindings.
@@ -42697,6 +42731,28 @@ function convertLegacyRecipe(legacy) {
 * it. The output type is always the new one.
 */
 var AutomationRecipeSchema = union([CurrentAutomationRecipeSchema, LegacyAutomationRecipeSchema.transform(convertLegacyRecipe)]);
+var DETECTION_DESCRIPTIONS = {
+	deviceId: "the camera that saw it",
+	className: "what it saw",
+	trackId: "the track",
+	score: "how sure the detector was",
+	label: "the label it matched (a name, a plate), empty when none"
+};
+var STATIONARY_DESCRIPTIONS = {
+	deviceId: "the camera that saw it",
+	className: "what it saw",
+	zones: "the zones it is in",
+	phase: "appeared or departed",
+	entryId: "the stopped object"
+};
+function describe$1(descriptions) {
+	return Object.entries(descriptions).map(([name, description]) => ({
+		name,
+		description
+	}));
+}
+describe$1(DETECTION_DESCRIPTIONS);
+describe$1(STATIONARY_DESCRIPTIONS);
 new Set(Object.values(COCO_TO_MACRO.mapping));
 /**
 * Schedulers (D983) — an entity that performs actions over the day.
@@ -53377,6 +53433,49 @@ method(_void(), paletteResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 });
+/**
+* do-not-disturb - whether a speaker or display holds back its own sounds
+* (announcements, notifications, alarms) until the operator lets it speak again.
+*
+* It is NOT part of `media-player`: a player is about what it plays and how
+* loud, while Do Not Disturb is a household switch the vendor keeps per device.
+* `enabled` is null when the vendor has not said (never a guess of `false`).
+*/
+var DoNotDisturbStatusSchema = object({
+	/** True while Do Not Disturb is on; null when unknown. */
+	enabled: boolean().nullable().meta({ label: "Do not disturb" }),
+	/** Ms epoch of the last read or write that set `enabled`. */
+	lastChangedAt: number$1()
+});
+var doNotDisturbCapability = {
+	name: "do-not-disturb",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [DeviceType.MediaPlayer],
+	methods: { setEnabled: method(object({
+		deviceId: number$1().int(),
+		enabled: boolean()
+	}), _void(), {
+		kind: "mutation",
+		auth: "protected"
+	}) },
+	status: {
+		schema: DoNotDisturbStatusSchema,
+		kind: "push"
+	},
+	runtimeState: DoNotDisturbStatusSchema,
+	/**
+	* Runtime-state durability: **session** - the vendor owns the switch and the
+	* device re-reads it on the next poll, so a restored value would only be stale.
+	*
+	* See `RuntimeStateDurability`. Enforced by
+	* `scripts/check-runtime-state-durability.ts`.
+	*/
+	durability: "session",
+	/** History (D850): when Do Not Disturb was switched on and off. */
+	history: { fields: { enabled: { kind: "boolean" } } }
+};
 /** Pulse override: a rising edge advances `lastPressedAt` and the press count. */
 var doorbellCustomize = {
 	version: 1,
@@ -55968,6 +56067,14 @@ var LlmGenerateBaseInputSchema = object({
 	topP: number$1().min(0).max(1).optional(),
 	/** Per-call override of the profile default (top-k sampling). */
 	topK: number$1().int().positive().optional(),
+	/** Per-call override of `profile.reasoningEffort`. Sent only to a kind whose
+	*  descriptor offers the field; a kind that does not never sends it. */
+	reasoningEffort: _enum([
+		"off",
+		"low",
+		"medium",
+		"high"
+	]).optional(),
 	/** Per-call override of `profile.timeoutMs` — the total generation bound. */
 	timeoutMs: number$1().int().positive().optional(),
 	/** Per-call override; beats both the consumer table and the profile. */
@@ -56259,7 +56366,10 @@ var LlmProfileKindSchema = string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "a kind i
 var LlmModelFeaturesSchema = object({
 	vision: boolean(),
 	tools: boolean(),
-	streaming: boolean()
+	streaming: boolean(),
+	/** Whether the model thinks before it answers. `null` = the endpoint does not
+	*  say; an editor then still offers the switch (unknown is not "no"). */
+	reasoning: boolean().nullable().optional()
 });
 /** One model a provider offers. `features` overrides the kind's defaults, per field. */
 var LlmModelInfoSchema = object({
@@ -74445,9 +74555,17 @@ var ServerUpdateActionResultSchema = object({
 	*/
 	requiredAddonUpdates: array(RequiredAddonUpdateSchema).optional()
 });
-var LaunchOverridesSchema = object({ 
-/** The persisted heap ceiling in MB, or `null` when none is set. */
-heapMb: number$1().int().nullable() });
+var LaunchOverridesSchema = object({
+	/** The persisted heap ceiling in MB, or `null` when none is set. */
+	heapMb: number$1().int().nullable(),
+	/** The persisted hub-main RSS budget in MB, or `null` when none is set. */
+	rssBudgetMb: number$1().int().nullable()
+});
+var SetLaunchOverridesInputSchema = object({
+	heapMb: number$1().int().min(512).max(65536).nullable(),
+	/** Omitted keeps the stored budget; `null` clears it. */
+	rssBudgetMb: number$1().int().min(512).max(65536).nullable().optional()
+});
 var SetLaunchOverridesResultSchema = LaunchOverridesSchema.extend({ 
 /** Always true: the override is read at launch, not by the running process. */
 restartRequired: boolean() });
@@ -74476,7 +74594,7 @@ method(_void(), ServerPackageStatusSchema, { auth: "admin" }), method(_void(), S
 }), method(_void(), ServerUpdateActionResultSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(_void(), LaunchOverridesSchema, { auth: "admin" }), method(object({ heapMb: number$1().int().min(512).max(65536).nullable() }), SetLaunchOverridesResultSchema, {
+}), method(_void(), LaunchOverridesSchema, { auth: "admin" }), method(SetLaunchOverridesInputSchema, SetLaunchOverridesResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 });
@@ -79582,6 +79700,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	deviceDiscovery: deviceDiscoveryCapability,
 	deviceStatus: deviceStatusCapability,
 	dishwasher: dishwasherCapability,
+	doNotDisturb: doNotDisturbCapability,
 	doorbell: doorbellCapability,
 	enumSensor: enumSensorCapability,
 	eventEmitter: eventEmitterCapability,
@@ -84035,6 +84154,20 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"doNotDisturb.getStatus": {
+		capName: "do-not-disturb",
+		capScope: "device",
+		addonId: null,
+		access: "view",
+		role: "viewer"
+	},
+	"doNotDisturb.setEnabled": {
+		capName: "do-not-disturb",
+		capScope: "device",
+		addonId: null,
+		access: "create",
+		role: "viewer"
+	},
 	"doorbell.getStatus": {
 		capName: "doorbell",
 		capScope: "device",
@@ -92223,6 +92356,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"doNotDisturb.getStatus": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"doNotDisturb.setEnabled": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"doorbell.getStatus": [{
 		name: "deviceId",
 		form: "single",
@@ -140378,6 +140521,13 @@ var ALEXA_BROKER_KIND = "alexa";
 var DEVICE_REFRESH_MS = 5 * 6e4;
 /** Where the addon serves the Alexa mark; `listTargetKinds` stamps it as `iconUrl`. */
 var ALEXA_SPEAK_ICON_URL = `/addon/${ALEXA_SPEAK_ADDON_ID}/icons/${ALEXA_SPEAK_KIND}`;
+/** How often an adopted Echo's player state is read (a push channel is a later phase). */
+var ECHO_POLL_MS = 3e4;
+/** One more read after a command, once Amazon has had time to apply it. */
+var ECHO_REREAD_MS = 1500;
+/** After a 429 the account is left alone for this long, doubling up to the cap. */
+var ECHO_RATE_BACKOFF_BASE_MS = 3e4;
+var ECHO_RATE_BACKOFF_MAX_MS = 5 * 6e4;
 //#endregion
 //#region src/alexa-broker-provider.ts
 /**
@@ -140607,6 +140757,37 @@ function buildAlexaApplianceCandidate(input) {
 function mappableAppliance(appliance) {
 	return mapAlexaCapabilitiesToCamStack(appliance.interfaces).capabilities.length > 0;
 }
+/** `echo:<serial>`: how an Echo is named among an account's adoption candidates. */
+var ECHO_NATIVE_ID_PREFIX = "echo:";
+function echoNativeId(serial) {
+	return `${ECHO_NATIVE_ID_PREFIX}${serial}`;
+}
+/** The serial an Echo candidate id names, or null when the id is not an Echo's. */
+function echoSerialOf(childNativeId) {
+	if (!childNativeId.startsWith("echo:")) return null;
+	const serial = childNativeId.slice(5);
+	return serial === "" ? null : serial;
+}
+/** An Echo the adoption list offers: a media player, a flat sibling under the Alexa integration. */
+function isAdoptableEcho(device) {
+	return device.kind === "device";
+}
+function buildAlexaEchoCandidate(input) {
+	const { device, adoptedDeviceId } = input;
+	return {
+		childNativeId: echoNativeId(device.id),
+		name: device.name.length > 0 ? device.name : device.id,
+		type: DeviceType.MediaPlayer,
+		status: device.online ? "online" : "offline",
+		metadata: {
+			manufacturer: "Amazon",
+			...device.room !== void 0 ? { externalLocation: device.room } : {}
+		},
+		alreadyAdopted: adoptedDeviceId !== null,
+		adoptedDeviceId,
+		capabilities: ["media-player", "do-not-disturb"]
+	};
+}
 //#endregion
 //#region src/alexa-adoption-provider.ts
 /** Single granularity: each Alexa appliance adopts as one device. */
@@ -140620,6 +140801,11 @@ async function adoptedApplianceId(brokerId, applianceId, listAdoptedAlexa) {
 	for (const d of await listAdoptedAlexa()) if (d.config["system"] === "alexa" && d.config["brokerId"] === brokerId && d.config["applianceId"] === applianceId) return d.id;
 	return null;
 }
+/** Resolve the adopted CamStack device id for a (broker, Echo serial), or null. */
+async function adoptedEchoId(brokerId, serial, listAdoptedAlexa) {
+	for (const d of await listAdoptedAlexa()) if (d.config["system"] === "alexa" && d.config["brokerId"] === brokerId && d.config["serial"] === serial) return d.id;
+	return null;
+}
 /**
 * Construct the `device-adoption` cap provider for the Alexa import addon. Pure
 * builder. One broker = one Amazon account; each mappable appliance is a flat
@@ -140627,7 +140813,7 @@ async function adoptedApplianceId(brokerId, applianceId, listAdoptedAlexa) {
 * Container fan-out — Alexa appliances are standalone devices).
 */
 function buildAlexaAdoptionProvider(deps) {
-	const { registry, getBrokerIdForIntegration, listAdoptedAlexa, adoptAppliance, removeDevice, findDeviceConfig, logger } = deps;
+	const { registry, getBrokerIdForIntegration, listAdoptedAlexa, adoptAppliance, adoptEcho, removeDevice, findDeviceConfig, logger } = deps;
 	async function candidatesForBroker(brokerId) {
 		const appliances = registry.getAppliancesForBroker(brokerId).filter(mappableAppliance);
 		const out = [];
@@ -140638,6 +140824,13 @@ function buildAlexaAdoptionProvider(deps) {
 				adoptedDeviceId
 			}));
 		}
+		for (const device of registry.getEchoesForBroker(brokerId).filter(isAdoptableEcho)) {
+			const adoptedDeviceId = await adoptedEchoId(brokerId, device.id, listAdoptedAlexa);
+			out.push(buildAlexaEchoCandidate({
+				device,
+				adoptedDeviceId
+			}));
+		}
 		return out;
 	}
 	return {
@@ -140692,7 +140885,41 @@ function buildAlexaAdoptionProvider(deps) {
 			const appliances = registry.getAppliancesForBroker(brokerId);
 			const adopted = [];
 			let failures = 0;
+			const echoes = registry.getEchoesForBroker(brokerId);
 			for (const nativeId of childNativeIds) {
+				const echoSerial = echoSerialOf(nativeId);
+				if (echoSerial !== null) {
+					const echo = echoes.find((device) => device.id === echoSerial && isAdoptableEcho(device));
+					if (echo === void 0) {
+						logger.warn("alexa adopt: Echo not found in the account — skipping", { meta: {
+							nativeId,
+							brokerId
+						} });
+						failures++;
+						continue;
+					}
+					try {
+						const { deviceId } = await adoptEcho({
+							brokerId,
+							echo,
+							integrationId,
+							name: perCandidate?.[nativeId]?.name ?? echo.name
+						});
+						adopted.push({
+							childNativeId: nativeId,
+							parentDeviceId: deviceId,
+							accessoryDeviceIds: []
+						});
+					} catch (err) {
+						logger.warn("alexa adopt: failed to adopt Echo", { meta: {
+							brokerId,
+							serial: echoSerial,
+							error: errMsg(err)
+						} });
+						failures++;
+					}
+					continue;
+				}
 				const appliance = appliances.find((a) => a.applianceId === nativeId);
 				if (appliance === void 0) {
 					logger.warn("alexa adopt: appliance not found in inventory — skipping", { meta: {
@@ -140785,6 +141012,7 @@ function setBrokerDevicesOnline(devices, brokerId, online) {
 	for (const dev of devices) {
 		if (dev.config.get("system") !== "alexa") continue;
 		if (dev.config.get("brokerId") !== brokerId) continue;
+		if (typeof dev.config.get("serial") === "string") continue;
 		if (dev.online === online) continue;
 		dev.markOnline(online);
 		count += 1;
@@ -141192,6 +141420,421 @@ var AlexaDevice = class extends BaseDevice {
 function isKnownCap(cap) {
 	return KNOWN_CAPS.has(cap);
 }
+var EchoSessionRegistry = class {
+	#resolve = null;
+	#dnd = /* @__PURE__ */ new Map();
+	setResolver(fn) {
+		this.#resolve = fn;
+	}
+	get(brokerId) {
+		return this.#resolve === null ? null : this.#resolve(brokerId);
+	}
+	/** Do Not Disturb of every device of the account. A failed read is not kept for the next device. */
+	dnd(brokerId, now) {
+		const shared = this.#dnd.get(brokerId);
+		if (shared !== void 0 && now - shared.at < 25e3) return shared.pending;
+		const session = this.get(brokerId);
+		if (session === null) return Promise.reject(/* @__PURE__ */ new Error("no Echo session for this account"));
+		const pending = session.dndState();
+		this.#dnd.set(brokerId, {
+			at: now,
+			pending
+		});
+		pending.catch(() => {
+			if (this.#dnd.get(brokerId)?.pending === pending) this.#dnd.delete(brokerId);
+		});
+		return pending;
+	}
+	clear() {
+		this.#resolve = null;
+		this.#dnd.clear();
+	}
+};
+/** The single in-process registry shared across the addon. */
+var alexaEchoSessions = new EchoSessionRegistry();
+//#endregion
+//#region src/alexa-echo-state-to-cap.ts
+/** The slice of an Echo that cannot be read: every reading null, the state as given. */
+function emptyEchoStatus(state, now) {
+	return {
+		state,
+		stateSource: "reported",
+		assumedFields: [],
+		volumeLevel: null,
+		isMuted: null,
+		source: "",
+		availableSources: [],
+		currentMedia: null,
+		position: null,
+		duration: null,
+		shuffle: null,
+		repeat: null,
+		lastChangedAt: now
+	};
+}
+function mapEchoPlaybackState(value) {
+	switch (value) {
+		case "PLAYING": return "playing";
+		case "PAUSED": return "paused";
+		case "BUFFERING": return "buffering";
+		default: return "idle";
+	}
+}
+function percent(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return null;
+	return Math.round(Math.max(0, Math.min(100, value)));
+}
+function secondsToMs(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
+	return Math.round(value * 1e3);
+}
+function nonEmpty(value) {
+	return typeof value === "string" && value !== "" ? value : null;
+}
+/** `SELECTED` is on, `UNSELECTED` is off; `HIDDEN` and `DISABLED` mean the surface does not exist. */
+function shuffleOf(value) {
+	if (value === "SELECTED") return true;
+	if (value === "UNSELECTED") return false;
+	return null;
+}
+function repeatOf(value) {
+	if (value === "SELECTED") return "all";
+	if (value === "UNSELECTED") return "off";
+	return null;
+}
+function currentMediaOf(info) {
+	const title = nonEmpty(info.infoText?.title);
+	if (title === null) return null;
+	const artist = nonEmpty(info.infoText?.subText1);
+	const album = nonEmpty(info.infoText?.subText2);
+	const imageUrl = nonEmpty(info.mainArt?.url);
+	return {
+		type: "unknown",
+		title,
+		...artist !== null ? { artist } : {},
+		...album !== null ? { album } : {},
+		...imageUrl !== null ? { imageUrl } : {}
+	};
+}
+function mapPlayerInfoToStatus(info, input) {
+	if (!input.online) return emptyEchoStatus("off", input.now);
+	const length = secondsToMs(info.progress?.mediaLength);
+	return {
+		...emptyEchoStatus(mapEchoPlaybackState(info.state), input.now),
+		volumeLevel: percent(info.volume?.volume),
+		isMuted: typeof info.volume?.muted === "boolean" ? info.volume.muted : null,
+		currentMedia: currentMediaOf(info),
+		position: secondsToMs(info.progress?.mediaProgress),
+		duration: length === 0 ? null : length,
+		shuffle: shuffleOf(info.transport?.shuffle),
+		repeat: repeatOf(info.transport?.repeat)
+	};
+}
+//#endregion
+//#region src/speak/worker-protocol.ts
+/** Line-delimited JSON the long-lived Python worker speaks. One object per line. */
+var EchoDeviceSchema = object({
+	id: string().min(1),
+	name: string(),
+	family: string(),
+	online: boolean(),
+	kind: _enum(["device", "group"]),
+	dnd: boolean(),
+	deviceType: string(),
+	/** The room the account files the device under, when Amazon names one. */
+	room: string().optional()
+});
+var LoginStatusSchema = _enum(["ok", "failed"]);
+var SessionStatusSchema = object({
+	loggedIn: boolean(),
+	ageSec: number$1().int().nonnegative(),
+	lastSuccessAt: number$1().int().nullable()
+});
+var TargetDeliverySchema = object({
+	targetId: string(),
+	ok: boolean(),
+	error: string().optional()
+});
+var WorkerLineSchema = union([object({
+	id: string(),
+	ok: literal(true),
+	result: unknown().optional()
+}), object({
+	id: string(),
+	ok: literal(false),
+	error: string(),
+	/** A typed reason the worker names; `rate-limited` is Amazon's 429. */
+	code: string().optional()
+})]);
+var RATE_LIMITED_CODE = "rate-limited";
+/** Amazon answered 429. Never an empty answer: the caller backs off and keeps what it had. */
+var RateLimitedError = class extends Error {
+	code = RATE_LIMITED_CODE;
+	constructor(message) {
+		super(message);
+		this.name = "RateLimitedError";
+	}
+};
+function requestLine(id, request) {
+	return `${JSON.stringify({
+		id,
+		...request
+	})}\n`;
+}
+function parseLoginResult(result) {
+	const parsed = object({
+		status: LoginStatusSchema,
+		error: string().optional()
+	}).safeParse(result);
+	if (!parsed.success) return {
+		status: "failed",
+		error: "worker returned an unexpected login result"
+	};
+	return parsed.data;
+}
+function parseDevices(result) {
+	const parsed = object({ devices: array(EchoDeviceSchema) }).safeParse(result);
+	if (!parsed.success) throw new Error("worker returned an unexpected device list");
+	return parsed.data.devices;
+}
+function parseDeliveries(result) {
+	const parsed = object({ outcomes: array(TargetDeliverySchema) }).safeParse(result);
+	if (!parsed.success) throw new Error("worker returned an unexpected delivery list");
+	return parsed.data.outcomes;
+}
+function parseSessionStatus(result) {
+	const parsed = SessionStatusSchema.safeParse(result);
+	if (!parsed.success) throw new Error("worker returned an unexpected session status");
+	return parsed.data;
+}
+/**
+* The raw `playerInfo` of `/api/np/player`. Amazon omits what it does not know,
+* so every field is nullable; the mapping to the media-player cap turns a missing
+* value into null, never into 0 (D393).
+*/
+var PlayerInfoSchema = object({
+	state: string().nullish(),
+	volume: object({
+		volume: number$1().nullish(),
+		muted: boolean().nullish()
+	}).nullish(),
+	infoText: object({
+		title: string().nullish(),
+		subText1: string().nullish(),
+		subText2: string().nullish()
+	}).nullish(),
+	mainArt: object({ url: string().nullish() }).nullish(),
+	progress: object({
+		mediaLength: number$1().nullish(),
+		mediaProgress: number$1().nullish()
+	}).nullish(),
+	transport: object({
+		shuffle: string().nullish(),
+		repeat: string().nullish()
+	}).nullish()
+});
+function parsePlayerState(result) {
+	const parsed = object({ playerInfo: PlayerInfoSchema.nullish() }).safeParse(result);
+	if (!parsed.success) throw new Error("worker returned an unexpected player state");
+	return parsed.data.playerInfo ?? {};
+}
+var DndEntrySchema = object({
+	serial: string().min(1),
+	enabled: boolean()
+});
+function parseDndState(result) {
+	const parsed = object({ devices: array(DndEntrySchema) }).safeParse(result);
+	if (!parsed.success) throw new Error("worker returned an unexpected Do Not Disturb list");
+	return new Map(parsed.data.devices.map((entry) => [entry.serial, entry.enabled]));
+}
+//#endregion
+//#region src/devices/alexa-echo-device.ts
+/**
+* An Echo is a media-player device. Identity only: the account (`brokerId`) and
+* the Echo's serial. The Echo's notification target is a separate record linked
+* by the same (brokerId, serial); nothing here sets or reads a notification.
+*/
+var alexaEchoDeviceSchema = object({
+	brokerId: string().min(1).describe("Registry broker id"),
+	serial: string().min(1).describe("The Echo serial number"),
+	deviceType: string().default("").describe("Amazon device type id"),
+	system: literal("alexa").optional(),
+	integrationId: string().optional()
+});
+var COLD_DND = {
+	enabled: null,
+	lastChangedAt: 0
+};
+function unsupported(what) {
+	throw new Error(`${what} is not available on an Echo`);
+}
+var AlexaEchoDevice = class extends BaseDevice {
+	features = [
+		DeviceFeature.MediaPlayerVolume,
+		DeviceFeature.MediaPlayerNext,
+		DeviceFeature.MediaPlayerPrevious
+	];
+	brokerId;
+	serial;
+	amazonDeviceType;
+	timer = null;
+	rereadTimer = null;
+	polling = false;
+	failureLogged = false;
+	health = "ok";
+	constructor(ctx) {
+		const persisted = alexaEchoDeviceSchema.parse(ctx.persistedConfig ?? {});
+		super(ctx, alexaEchoDeviceSchema, { type: DeviceType.MediaPlayer });
+		this.brokerId = persisted.brokerId;
+		this.serial = persisted.serial;
+		this.amazonDeviceType = persisted.deviceType;
+	}
+	/** The outcome of the last read, for the broker status and the specs. */
+	get pollHealth() {
+		return this.health;
+	}
+	async onActivate() {
+		await super.onActivate();
+		this.registerMediaPlayer();
+		this.registerDoNotDisturb();
+		this.runtimeState.setCapState("media-player", emptyEchoStatus("off", 0));
+		this.runtimeState.setCapState("do-not-disturb", COLD_DND);
+		this.poll();
+		this.timer = setInterval(() => void this.poll(), ECHO_POLL_MS);
+		this.timer.unref();
+	}
+	async removeDevice() {
+		if (this.timer !== null) clearInterval(this.timer);
+		if (this.rereadTimer !== null) clearTimeout(this.rereadTimer);
+		this.timer = null;
+		this.rereadTimer = null;
+		await super.removeDevice();
+	}
+	session() {
+		const session = alexaEchoSessions.get(this.brokerId);
+		if (session === null) throw new Error("the Amazon account of this Echo is not connected");
+		return session;
+	}
+	/** One re-read shortly after a command, once Amazon has applied it. */
+	rereadSoon() {
+		if (this.rereadTimer !== null) clearTimeout(this.rereadTimer);
+		this.rereadTimer = setTimeout(() => {
+			this.rereadTimer = null;
+			this.poll();
+		}, ECHO_REREAD_MS);
+		this.rereadTimer.unref();
+	}
+	/**
+	* Read the player and Do Not Disturb. A failed read leaves both slices as they
+	* were and marks the device degraded; a 429 is a pause, not a fault. Never throws.
+	*/
+	async poll() {
+		if (this.polling) return;
+		this.polling = true;
+		try {
+			await this.readOnce();
+		} finally {
+			this.polling = false;
+		}
+	}
+	async readOnce() {
+		const session = alexaEchoSessions.get(this.brokerId);
+		if (session === null || session.state !== "ready") return;
+		if (session.rateLimitedUntil !== null) {
+			this.health = "rate-limited";
+			return;
+		}
+		const listed = session.devices.find((device) => device.id === this.serial);
+		if (listed !== void 0 && !listed.online) {
+			this.runtimeState.setCapState("media-player", emptyEchoStatus("off", Date.now()));
+			this.markOnline(false);
+			this.health = "ok";
+			return;
+		}
+		const deviceType = this.amazonDeviceType !== "" ? this.amazonDeviceType : listed?.deviceType ?? "";
+		try {
+			const info = await session.playerState(this.serial, deviceType);
+			const now = Date.now();
+			this.runtimeState.setCapState("media-player", mapPlayerInfoToStatus(info, {
+				online: true,
+				now
+			}));
+			this.markOnline(true);
+			this.noteRecovered();
+		} catch (err) {
+			this.noteReadFailure(err);
+			return;
+		}
+		await this.readDoNotDisturb();
+	}
+	async readDoNotDisturb() {
+		try {
+			const enabled = (await alexaEchoSessions.dnd(this.brokerId, Date.now())).get(this.serial);
+			if (enabled === void 0) return;
+			this.runtimeState.setCapState("do-not-disturb", {
+				enabled,
+				lastChangedAt: Date.now()
+			});
+		} catch (err) {
+			this.noteReadFailure(err);
+		}
+	}
+	noteRecovered() {
+		if (this.failureLogged) this.ctx.logger.info("alexa echo: reads are working again", { tags: { deviceId: this.id } });
+		this.failureLogged = false;
+		this.health = "ok";
+	}
+	noteReadFailure(err) {
+		if (err instanceof RateLimitedError) {
+			this.health = "rate-limited";
+			this.ctx.logger.info("alexa echo: amazon asked for a pause, keeping the last state", { tags: { deviceId: this.id } });
+			return;
+		}
+		this.health = "degraded";
+		if (this.failureLogged) return;
+		this.failureLogged = true;
+		this.ctx.logger.warn("alexa echo: could not read the player, keeping the last state", {
+			tags: { deviceId: this.id },
+			meta: { error: err instanceof Error ? err.message : String(err) }
+		});
+	}
+	async command(command) {
+		await this.session().npCommand(this.serial, command);
+		this.rereadSoon();
+	}
+	registerMediaPlayer() {
+		this.ctx.registerNativeCap(mediaPlayerCapability, {
+			getStatus: async () => this.runtimeState.getCapState("media-player") ?? emptyEchoStatus("off", 0),
+			play: () => this.command("play"),
+			pause: () => this.command("pause"),
+			next: () => this.command("next"),
+			previous: () => this.command("previous"),
+			setVolume: async ({ volumeLevel }) => {
+				await this.session().setVolume(this.serial, Math.round(volumeLevel));
+				this.rereadSoon();
+			},
+			stop: async () => unsupported("stop"),
+			seek: async () => unsupported("seek"),
+			setMute: async () => unsupported("mute"),
+			setShuffle: async () => unsupported("shuffle"),
+			setRepeat: async () => unsupported("repeat"),
+			selectSource: async () => unsupported("source selection"),
+			playMedia: async () => unsupported("playing media")
+		});
+	}
+	registerDoNotDisturb() {
+		this.ctx.registerNativeCap(doNotDisturbCapability, {
+			getStatus: async () => this.runtimeState.getCapState("do-not-disturb") ?? COLD_DND,
+			setEnabled: async ({ enabled }) => {
+				await this.session().setDnd(this.serial, enabled);
+				this.runtimeState.setCapState("do-not-disturb", {
+					enabled,
+					lastChangedAt: Date.now()
+				});
+			}
+		});
+	}
+};
 var alexaBrokersEntryKind = defineEntryKind("brokers", {
 	title: "Alexa import brokers",
 	schema: entryBody({
@@ -141500,78 +142143,14 @@ function scrubSecrets(text, secrets) {
 	return out;
 }
 //#endregion
-//#region src/speak/worker-protocol.ts
-/** Line-delimited JSON the long-lived Python worker speaks. One object per line. */
-var EchoDeviceSchema = object({
-	id: string().min(1),
-	name: string(),
-	family: string(),
-	online: boolean(),
-	kind: _enum(["device", "group"]),
-	dnd: boolean(),
-	deviceType: string(),
-	/** The room the account files the device under, when Amazon names one. */
-	room: string().optional()
-});
-var LoginStatusSchema = _enum(["ok", "failed"]);
-var SessionStatusSchema = object({
-	loggedIn: boolean(),
-	ageSec: number$1().int().nonnegative(),
-	lastSuccessAt: number$1().int().nullable()
-});
-var TargetDeliverySchema = object({
-	targetId: string(),
-	ok: boolean(),
-	error: string().optional()
-});
-var WorkerLineSchema = union([object({
-	id: string(),
-	ok: literal(true),
-	result: unknown().optional()
-}), object({
-	id: string(),
-	ok: literal(false),
-	error: string()
-})]);
-function requestLine(id, request) {
-	return `${JSON.stringify({
-		id,
-		...request
-	})}\n`;
-}
-function parseLoginResult(result) {
-	const parsed = object({
-		status: LoginStatusSchema,
-		error: string().optional()
-	}).safeParse(result);
-	if (!parsed.success) return {
-		status: "failed",
-		error: "worker returned an unexpected login result"
-	};
-	return parsed.data;
-}
-function parseDevices(result) {
-	const parsed = object({ devices: array(EchoDeviceSchema) }).safeParse(result);
-	if (!parsed.success) throw new Error("worker returned an unexpected device list");
-	return parsed.data.devices;
-}
-function parseDeliveries(result) {
-	const parsed = object({ outcomes: array(TargetDeliverySchema) }).safeParse(result);
-	if (!parsed.success) throw new Error("worker returned an unexpected delivery list");
-	return parsed.data.outcomes;
-}
-function parseSessionStatus(result) {
-	const parsed = SessionStatusSchema.safeParse(result);
-	if (!parsed.success) throw new Error("worker returned an unexpected session status");
-	return parsed.data;
-}
-//#endregion
 //#region src/speak/broker-echo.ts
 var BrokerEcho = class {
 	deps;
 	currentState = "starting";
 	currentError = null;
 	currentDevices = [];
+	backoffMs = 0;
+	limitedUntil = 0;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -141590,6 +142169,13 @@ var BrokerEcho = class {
 	get devices() {
 		return this.currentDevices;
 	}
+	/** Ms epoch until which Amazon asked us to wait (429), or null when the account is free. */
+	get rateLimitedUntil() {
+		return this.limitedUntil > this.nowMs() ? this.limitedUntil : null;
+	}
+	nowMs() {
+		return (this.deps.now ?? Date.now)();
+	}
 	stop() {
 		this.deps.worker.stop();
 	}
@@ -141680,6 +142266,69 @@ var BrokerEcho = class {
 			text
 		}));
 	}
+	/**
+	* Run one worker call. A 429 starts (or doubles) the account's back-off and is
+	* rethrown as is; any answer ends it. Rate limiting is a status, not a failure.
+	*/
+	async limited(call) {
+		try {
+			const result = await call();
+			this.backoffMs = 0;
+			this.limitedUntil = 0;
+			return result;
+		} catch (err) {
+			if (err instanceof RateLimitedError) {
+				this.backoffMs = this.backoffMs === 0 ? ECHO_RATE_BACKOFF_BASE_MS : Math.min(this.backoffMs * 2, ECHO_RATE_BACKOFF_MAX_MS);
+				this.limitedUntil = this.nowMs() + this.backoffMs;
+				this.deps.logger.info("alexa echo: amazon asked for a pause (429)", {
+					tags: { brokerId: this.deps.brokerId },
+					meta: { backoffMs: this.backoffMs }
+				});
+			}
+			throw err;
+		}
+	}
+	/** The raw player state of one Echo. Throws on any failure, a 429 included: never an empty answer. */
+	async playerState(serial, deviceType) {
+		await this.requireReady();
+		return this.limited(async () => parsePlayerState(await this.deps.worker.request({
+			op: "player_state",
+			serial,
+			deviceType
+		})));
+	}
+	async npCommand(serial, command) {
+		await this.requireReady();
+		await this.limited(() => this.deps.worker.request({
+			op: "np_command",
+			serial,
+			command
+		}));
+	}
+	async setVolume(serial, level) {
+		await this.requireReady();
+		await this.limited(() => this.deps.worker.request({
+			op: "set_volume",
+			serial,
+			level
+		}));
+	}
+	/** Do Not Disturb of every device of the account, by serial, in one call. */
+	async dndState() {
+		await this.requireReady();
+		return this.limited(async () => parseDndState(await this.deps.worker.request({ op: "dnd_state" })));
+	}
+	async setDnd(serial, enabled) {
+		await this.requireReady();
+		await this.limited(() => this.deps.worker.request({
+			op: "set_dnd",
+			serial,
+			enabled
+		}));
+	}
+	async requireReady() {
+		if (!await this.ensureReady()) throw new Error(this.notReadyReason());
+	}
 	async session() {
 		if (this.deps.worker.failed) return {
 			loggedIn: false,
@@ -142402,6 +143051,7 @@ function startAlexaWorker(deps) {
 		const current = pending;
 		pending = null;
 		if (message.ok) current.resolve(message.result);
+		else if (message.code === "rate-limited") current.reject(new RateLimitedError(scrub(message.error)));
 		else current.reject(new Error(scrub(message.error)));
 		pump();
 	}
@@ -142555,6 +143205,10 @@ var AlexaSpeakController = class {
 		this.queue = this.queue.then(() => this.reconcile()).catch(() => void 0);
 		return this.queue;
 	}
+	/** The live session of one account, for the Echo devices that poll it. */
+	echoFor(brokerId) {
+		return this.echoes.get(brokerId) ?? null;
+	}
 	brokerViews() {
 		return this.host.listBrokers().map((ref) => {
 			const echo = this.echoes.get(ref.id);
@@ -142562,7 +143216,8 @@ var AlexaSpeakController = class {
 				id: ref.id,
 				name: ref.name,
 				ready: echo?.state === "ready",
-				devices: echo?.devices ?? []
+				devices: echo?.devices ?? [],
+				rateLimitedUntil: echo?.rateLimitedUntil ?? null
 			};
 		});
 	}
@@ -142606,7 +143261,8 @@ var AlexaSpeakController = class {
 			worker: this.makeWorker(ref.id, pythonPath),
 			readSeed: () => this.host.readSeed(ref.id),
 			sessions: this.host.sessions,
-			logger: this.host.logger
+			logger: this.host.logger,
+			now: this.now
 		}));
 		await Promise.all(refs.map(async (ref) => {
 			const echo = this.echoes.get(ref.id);
@@ -142765,7 +143421,10 @@ var ALEXA_DEVICE_TYPES = [
 var AlexaImportAddon = class extends BaseDeviceProvider {
 	addonId = "import-alexa";
 	providerName = "Alexa";
-	deviceClasses = Object.fromEntries(ALEXA_DEVICE_TYPES.map((t) => [t, AlexaDevice]));
+	deviceClasses = {
+		...Object.fromEntries(ALEXA_DEVICE_TYPES.map((t) => [t, AlexaDevice])),
+		[DeviceType.MediaPlayer]: AlexaEchoDevice
+	};
 	registry = null;
 	proxyLogin = null;
 	deviceCodeLogin = null;
@@ -142852,6 +143511,7 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 			ensurePython: () => this.ctx.deps.ensurePython()
 		});
 		this.speak = speak;
+		alexaEchoSessions.setResolver((brokerId) => speak.echoFor(brokerId));
 		speak.start().catch((err) => {
 			this.ctx.logger.warn("alexa speak: worker did not start", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		});
@@ -142956,6 +143616,7 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 	async onShutdown() {
 		this.speak?.stop();
 		this.speak = null;
+		alexaEchoSessions.clear();
 		alexaCommands.clear();
 		try {
 			await this.proxyLogin?.dispose();
@@ -142979,7 +143640,10 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 	}
 	/** One broker = one account; the appliance id distinguishes devices within it. */
 	generateStableId(_type, config) {
-		return `alexa:${String(config?.["brokerId"] ?? "unknown")}:${String(config?.["applianceId"] ?? "unknown")}`;
+		const brokerId = String(config?.["brokerId"] ?? "unknown");
+		const serial = config?.["serial"];
+		if (typeof serial === "string") return `alexa:${brokerId}:echo:${serial}`;
+		return `alexa:${brokerId}:${String(config?.["applianceId"] ?? "unknown")}`;
 	}
 	/**
 	* Re-derive every adopted Alexa device's `capabilities[]` from the live
@@ -143142,7 +143806,8 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 					id: b.id,
 					name: b.name
 				})),
-				has: (id) => this.requireRegistry().get(id) !== null
+				has: (id) => this.requireRegistry().get(id) !== null,
+				getEchoesForBroker: (id) => this.speak?.echoFor(id)?.devices ?? []
 			},
 			logger: this.ctx.logger,
 			getBrokerIdForIntegration: async (id) => {
@@ -143184,6 +143849,23 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 					integrationId
 				})).id };
 			},
+			adoptEcho: async ({ brokerId, echo, integrationId, name }) => {
+				const devices = this.ctx.kernel.devices;
+				if (!devices) throw new Error("alexa adopt: kernel.devices unavailable");
+				const config = {
+					brokerId,
+					serial: echo.id,
+					deviceType: echo.deviceType,
+					system: "alexa",
+					integrationId,
+					name
+				};
+				return { deviceId: (await devices.create(this.generateStableId(DeviceType.MediaPlayer, config), AlexaEchoDevice, config, null, {
+					type: DeviceType.MediaPlayer,
+					name,
+					integrationId
+				})).id };
+			},
 			removeDevice: async (id) => {
 				await this.ctx.kernel.devices?.remove(id);
 			},