@camstack/system 1.0.2

package/dist/addon-runner.mjs

@@ -0,0 +1,597 @@
+import { $ as setWorkerNativeCapsChangeListener, A as createUdsLoggerWithControl, L as LocalChildClient, X as getWorkerNativeCapProvider, Z as getWorkerNativeCapSnapshot, dt as CustomActionRegistry, i as createUdsAddonContext, mt as resolveAddonClass, t as installManifestPythonDeps, tt as validateProviderRegistrations } from "./manifest-python-deps-DZsKTbs1.mjs";
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
+import { ReadinessRegistry, ReadinessTimeoutError, errMsg, normalizeAddonInitResult } from "@camstack/types";
+//#region src/kernel/moleculer/worker-device-restore.ts
+/**
+* Worker-side device restore helper.
+*
+* Shared by `process-runner` (single-addon subprocess) and
+* `group-runner` (group subprocess). Calls the worker addon's
+* `restoreDevices(SavedDevice[])` with devices read from the hub's
+* `device-manager` capability. Blocks on the `system.ready-state`
+* readiness of the hub's `device-manager` via
+* `ReadinessRegistry.awaitReady`, then issues the calls ONCE.
+*
+* Lives in its own module so it can be imported without triggering
+* the runner entry-point side effects (each runner is also an
+* executable that calls `main()` at import time).
+*/
+async function runWorkerDeviceRestoreWithRetry(addon, context, addonId, sourceNodeId) {
+	const log = context.logger;
+	log?.debug?.(`[worker-restore] entry: addon="${addonId}" sourceNodeId="${sourceNodeId}"`);
+	const restoreFn = addon.restoreDevices;
+	if (typeof restoreFn !== "function") {
+		log?.warn?.(`[worker-restore] "${addonId}": no restoreDevices function — skipping`);
+		return;
+	}
+	const api = context.api;
+	if (!api) {
+		log?.warn?.(`[worker-restore] "${addonId}": context.api missing — skipping`);
+		return;
+	}
+	const bus = context.eventBus;
+	if (!bus) {
+		log?.warn?.(`[worker-restore] "${addonId}": context.eventBus missing — skipping`);
+		return;
+	}
+	const shared = context.kernel?.readinessRegistry ?? null;
+	const registry = shared ?? new ReadinessRegistry({
+		eventBus: bus,
+		sourceNodeId,
+		logger: context.logger
+	});
+	log?.debug?.(`[worker-restore] "${addonId}": awaiting device-manager readiness on hub...`);
+	try {
+		await registry.awaitReady("device-manager", {
+			type: "node",
+			nodeId: "hub"
+		}, { timeoutMs: 6e4 });
+		log?.debug?.(`[worker-restore] "${addonId}": device-manager READY`);
+	} catch (err) {
+		if (err instanceof ReadinessTimeoutError) {
+			context.logger?.warn?.(`[worker-restore] device-manager not ready within ${err.waitedMs}ms — skipping for "${addonId}"`);
+			return;
+		}
+		throw err;
+	} finally {
+		if (!shared && registry instanceof ReadinessRegistry) registry.close();
+	}
+	try {
+		const deviceManager = Reflect.get(api, "deviceManager");
+		log?.debug?.(`[worker-restore] "${addonId}": calling listPersistedByAddon...`);
+		const rowsResult = await deviceManager.listPersistedByAddon.query({ addonId });
+		log?.debug?.(`[worker-restore] "${addonId}": got ${Array.isArray(rowsResult) ? rowsResult.length : 0} row(s)`);
+		const rows = Array.isArray(rowsResult) ? rowsResult : [];
+		if (rows.length === 0) {
+			context.logger?.info?.(`[worker-restore] no persisted devices to restore for addon "${addonId}"`);
+			return;
+		}
+		const savedDevices = await Promise.all(rows.map(async (row) => {
+			const config = await deviceManager.loadConfig.query({ deviceId: row.id });
+			return {
+				id: row.id,
+				stableId: row.stableId,
+				type: row.type,
+				name: row.name,
+				parentDeviceId: row.parentDeviceId,
+				config: config ?? {}
+			};
+		}));
+		await restoreFn.call(addon, savedDevices);
+		log?.info?.(`[worker-restore] "${addonId}": restored ${savedDevices.length} device(s)`);
+	} catch (err) {
+		log?.warn?.(`[worker-restore] "${addonId}": restoreDevices threw: ${errMsg(err)}`);
+	}
+}
+//#endregion
+//#region src/kernel/moleculer/child-cap-dispatch.ts
+/** Type guard narrowing a dynamically-read provider member to a callable method. */
+function isCapMethod(value) {
+	return typeof value === "function";
+}
+/**
+* Creates a unified dispatcher that routes a {@link CapCallInput} to either a
+* device-scoped or singleton provider, then invokes the requested method.
+*
+* Pure module — no Moleculer, no broker, no addon-runner dependency.
+*/
+function createChildCapDispatch(deps) {
+	return async (call) => {
+		const { capName, method, args, deviceId } = call;
+		let provider;
+		if (deviceId !== void 0) {
+			provider = deps.getDeviceProvider(capName, deviceId) ?? deps.getSingletonProvider(capName);
+			if (provider == null) throw new Error(`child-cap-dispatch: no provider for '${capName}' (device '${String(deviceId)}' or singleton)`);
+		} else {
+			provider = deps.getSingletonProvider(capName);
+			if (provider == null) throw new Error(`child-cap-dispatch: no singleton provider for '${capName}'`);
+		}
+		const fn = Reflect.get(provider, method);
+		if (!isCapMethod(fn)) throw new Error(`child-cap-dispatch: method '${method}' not found on provider '${capName}'`);
+		return await fn.call(provider, args);
+	};
+}
+//#endregion
+//#region src/kernel/moleculer/child-addon-call-dispatch.ts
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Strip the (non-serializable) `handler` from a route descriptor, keeping only
+* the keys the hub needs to mount + describe the route. The hub bridges actual
+* dispatch through the `addon-routes` cap's `invoke` method, so the handler
+* never needs to cross the wire.
+*/
+function toSerializableRoute(route) {
+	if (!isRecord$1(route)) throw new Error("child-addon-call: getRoutes() returned a non-object route descriptor");
+	const method = route["method"];
+	const path = route["path"];
+	if (typeof method !== "string" || typeof path !== "string") throw new Error("child-addon-call: route descriptor missing method/path");
+	const access = route["access"];
+	const description = route["description"];
+	return {
+		method,
+		path,
+		...typeof access === "string" ? { access } : {},
+		...typeof description === "string" ? { description } : {}
+	};
+}
+/**
+* Dispatch a `target: 'settings'` addon-call to the loaded addon instance.
+* Mirrors the (removed) `<addonId>.settings.<method>` Moleculer action. The
+* inner `method` switch is also exhaustive (`never` check) so a new settings
+* method added to `AddonSettingsMethod` must be handled here too. Returns the
+* raw method result; the hub reshapes get-results and acks updates.
+*/
+async function dispatchSettings(addon, addonId, method, args) {
+	switch (method) {
+		case "getGlobalSettings": return typeof addon.getGlobalSettings === "function" ? await addon.getGlobalSettings(args.overlay, args.cap) ?? null : null;
+		case "updateGlobalSettings":
+			if (typeof addon.updateGlobalSettings !== "function") throw new Error(`child-addon-call: addon "${addonId}" does not implement updateGlobalSettings`);
+			await addon.updateGlobalSettings(args.patch ?? {});
+			return { success: true };
+		case "getDeviceSettings": return typeof addon.getDeviceSettings === "function" && typeof args.deviceId === "number" ? await addon.getDeviceSettings(args.deviceId) ?? null : null;
+		case "updateDeviceSettings":
+			if (typeof addon.updateDeviceSettings !== "function") throw new Error(`child-addon-call: addon "${addonId}" does not implement updateDeviceSettings`);
+			if (typeof args.deviceId !== "number") throw new Error(`child-addon-call: addon "${addonId}" updateDeviceSettings missing deviceId`);
+			await addon.updateDeviceSettings(args.deviceId, args.patch ?? {});
+			return { success: true };
+		default: throw new Error(`child-addon-call: unhandled settings method "${String(method)}"`);
+	}
+}
+/**
+* Creates the addon-level dispatcher the addon-runner wires to
+* `LocalChildClient.onAddonCall`. Routes a {@link AddonCallInput} to one of the
+* exhaustive {@link AddonCallTarget} surfaces (routes / custom / settings) —
+* everything the per-addon Moleculer broker used to carry before the UDS
+* migration removed it. The `target` switch is exhaustive (`never` check): a
+* new surface added to the protocol union that isn't dispatched here is a
+* COMPILE ERROR — the guard that makes a "missed link" impossible.
+*
+* Pure module — no Moleculer, no broker, no addon-runner dependency.
+*/
+function createChildAddonCallDispatch(deps) {
+	return async (call) => {
+		const { addonId, target } = call;
+		switch (target) {
+			case "routes": {
+				const provider = deps.getRouteProvider(addonId);
+				if (provider == null) throw new Error(`child-addon-call: addon "${addonId}" has no addon-routes provider`);
+				const getRoutes = Reflect.get(provider, "getRoutes");
+				if (typeof getRoutes !== "function") throw new Error(`child-addon-call: addon "${addonId}" addon-routes provider has no getRoutes()`);
+				const live = await getRoutes.call(provider);
+				if (!Array.isArray(live)) throw new Error(`child-addon-call: addon "${addonId}" getRoutes() did not return an array`);
+				return live.map(toSerializableRoute);
+			}
+			case "custom": {
+				const action = call.action;
+				if (typeof action !== "string" || action.length === 0) throw new Error(`child-addon-call: addon "${addonId}" custom call missing action name`);
+				const entry = deps.customActions.resolve(addonId, action);
+				if (entry === null) throw new Error(`child-addon-call: addon "${addonId}" has no custom action "${action}"`);
+				return entry.handler(call.args);
+			}
+			case "settings": {
+				const method = call.method;
+				if (method == null) throw new Error(`child-addon-call: addon "${addonId}" settings call missing method`);
+				const addon = deps.getAddonInstance(addonId);
+				if (addon == null) throw new Error(`child-addon-call: addon "${addonId}" not loaded on this node`);
+				return dispatchSettings(addon, addonId, method, call.args ?? {});
+			}
+			case "data-planes": return deps.getDataPlanes(addonId);
+			default: throw new Error(`child-addon-call: unhandled addon-call target "${String(target)}"`);
+		}
+	};
+}
+//#endregion
+//#region src/kernel/moleculer/addon-runner.ts
+/**
+* Addon Runner — THE unified entry point for spawned subprocesses.
+*
+* Every spawned process is a size-1 addon set — one addon, one process,
+* zero exceptions (D2/D9). The media-pipeline co-location group was
+* dissolved by Phase 5 once frames and audio chunks became serialisable
+* (shm `FrameHandle`s / tRPC), so no addon declares `execution.group`
+* and `CAMSTACK_RUNNER_ADDONS` always carries a single element. The
+* runner still accepts a multi-element array structurally — that is a
+* mechanism, not a policy; no manifest exercises it.
+*
+* UDS-ONLY (Phase F1+F2 — irreversible). The forked child runs with NO
+* Moleculer `ServiceBroker`. Its only link to the parent (hub or agent)
+* is a `LocalChildClient` over a Unix-domain socket:
+*
+*   - Caps:      `ctx.api.<cap>.<method>(...)` resolves a same-process
+*                sibling via `localProviderLink`; everything else rides
+*                `ipcParentLink → client.callOut` → the parent's
+*                `onUnownedCall` (resolver-first + broker-fallback) — F0.
+*   - Events:    `createUdsEventBus` — local `deliverShared` + UDS forward.
+*   - Logs:      `createUdsLogger` — `client.sendLog` (pre-connect buffered).
+*   - Readiness: `getOrInitReadinessRegistryForClient` — hydrate via
+*                `client.requestReadinessSnapshot()` on connect.
+*   - Registration: the UDS `register`/`updateCaps` message IS the
+*                handshake (the parent applies it via `onChildRegistered`,
+*                mirroring `$hub.registerNode`). No Moleculer RPC.
+*
+* CRITICAL ORDERING: `udsChildClient.start()` MUST resolve BEFORE any addon
+* module is loaded/initialised — addon `initialize()` issues `ctx.api` /
+* `ctx.settings` calls that route over UDS via `ipcParentLink`, and there is
+* no broker fallback anymore. The client's pre-connect buffers flush on
+* connect, so init-time logs/events are preserved.
+*
+* Environment variables:
+* - CAMSTACK_RUNNER_ID        — runner label (becomes the nodeID suffix)
+* - CAMSTACK_RUNNER_ADDONS    — JSON array of `{ addonId, addonDir }`
+* - CAMSTACK_PARENT_NODE_ID   — hub or agent nodeID
+* - CAMSTACK_PARENT_UDS_PATH  — REQUIRED: the parent's UDS endpoint
+* - CAMSTACK_DATA_DIR         — addon data root (default ./camstack-data)
+* - CAMSTACK_LOG_LEVEL        — log level (default debug)
+*
+* Exits non-zero on fatal init failures so the parent process supervisor
+* can respawn. Graceful SIGTERM/SIGINT triggers `addon.shutdown()` for
+* every loaded addon before closing the UDS channel.
+*/
+process.on("uncaughtException", (err) => {
+	console.error(`[addon-runner CRASH] uncaughtException: ${errMsg(err)}\n${err instanceof Error ? err.stack ?? "" : ""}`);
+	process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+	console.error(`[addon-runner CRASH] unhandledRejection: ${errMsg(reason)}\n${reason instanceof Error ? reason.stack ?? "" : ""}`);
+});
+process.on("exit", (code) => {
+	console.error(`[addon-runner EXIT] code=${String(code)} nodeId=${process.env["CAMSTACK_RUNNER_ID"] ?? "?"}`);
+});
+for (const sig of [
+	"SIGTERM",
+	"SIGINT",
+	"SIGHUP"
+]) process.on(sig, () => {
+	console.error(`[addon-runner SIGNAL] received ${sig} nodeId=${process.env["CAMSTACK_RUNNER_ID"] ?? "?"}`);
+});
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseAddonsSpec(raw) {
+	if (!raw) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`[addon-runner] CAMSTACK_RUNNER_ADDONS is not valid JSON: ${errMsg(err)}`, { cause: err });
+	}
+	if (!Array.isArray(parsed)) throw new Error(`[addon-runner] CAMSTACK_RUNNER_ADDONS must be a JSON array`);
+	const specs = [];
+	for (const entry of parsed) {
+		if (!isRecord(entry)) throw new Error(`[addon-runner] addon spec is not an object: ${JSON.stringify(entry)}`);
+		const addonId = entry["addonId"];
+		const addonDir = entry["addonDir"];
+		if (typeof addonId !== "string" || typeof addonDir !== "string") throw new Error(`[addon-runner] addon spec missing addonId/addonDir: ${JSON.stringify(entry)}`);
+		specs.push({
+			addonId,
+			addonDir
+		});
+	}
+	return specs;
+}
+async function loadAddonModule(addonId, addonDir) {
+	const pkgJsonPath = path$1.join(addonDir, "package.json");
+	if (!fs.existsSync(pkgJsonPath)) throw new Error(`No package.json at ${addonDir}`);
+	const declaration = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"))["camstack"]?.addons?.find((a) => a.id === addonId);
+	if (!declaration?.entry) throw new Error(`Addon "${addonId}" not found in ${pkgJsonPath} manifest`);
+	const entryPath = path$1.resolve(addonDir, declaration.entry);
+	if (!fs.existsSync(entryPath)) throw new Error(`Entry point not found: ${entryPath}`);
+	const modUnknown = await import(entryPath);
+	const mod = isRecord(modUnknown) ? modUnknown : {};
+	const AddonClass = resolveAddonClass(mod);
+	if (!AddonClass) throw new Error(`No addon class exported from ${entryPath}`);
+	return {
+		declaration,
+		mod,
+		AddonClass
+	};
+}
+/**
+* Builds the {@link ChildCapDescriptor} array that the UDS child transport
+* sends to the parent on registration.
+*
+* - Singleton caps come from the runner UNION manifest (all caps registered by
+*   every addon in this runner). One descriptor per unique cap name, mode
+*   `'singleton'` and no `deviceId`.
+* - Device-scoped caps come from the native-cap snapshot — one descriptor per
+*   (capName, deviceId) pair, mode `'collection'`.
+*/
+function buildChildCapDescriptors(manifest, nativeCapSnapshot) {
+	const descriptors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of manifest) for (const capName of entry.capabilities) if (!seen.has(capName)) {
+		seen.add(capName);
+		descriptors.push({
+			capName,
+			mode: "singleton"
+		});
+	}
+	for (const { capName, deviceIds } of nativeCapSnapshot) for (const deviceId of deviceIds) descriptors.push({
+		capName,
+		mode: "collection",
+		deviceId
+	});
+	return descriptors;
+}
+async function main() {
+	const runnerId = process.env["CAMSTACK_RUNNER_ID"];
+	const addonsJson = process.env["CAMSTACK_RUNNER_ADDONS"];
+	const parentNodeId = process.env["CAMSTACK_PARENT_NODE_ID"];
+	const dataDir = process.env["CAMSTACK_DATA_DIR"] ?? "./camstack-data";
+	if (!runnerId || !addonsJson || !parentNodeId) {
+		console.error("[addon-runner] Missing required env vars: CAMSTACK_RUNNER_ID, CAMSTACK_RUNNER_ADDONS, CAMSTACK_PARENT_NODE_ID");
+		process.exit(1);
+	}
+	let specs;
+	try {
+		specs = parseAddonsSpec(addonsJson);
+	} catch (err) {
+		console.error(errMsg(err));
+		process.exit(1);
+	}
+	if (specs.length === 0) {
+		console.error("[addon-runner] CAMSTACK_RUNNER_ADDONS resolved to 0 addons — refusing to start");
+		process.exit(1);
+	}
+	const nodeId = `${parentNodeId}/${runnerId}`;
+	if (!process.env["CAMSTACK_PARENT_UDS_PATH"]) {
+		console.error(`[addon-runner] "${nodeId}" CAMSTACK_PARENT_UDS_PATH is unset — broker-less runner cannot reach its parent. Exiting.`);
+		process.exit(1);
+	}
+	console.log(`[addon-runner] Starting "${nodeId}" (UDS-only) with ${specs.length} addon(s): ${specs.map((s) => s.addonId).join(", ")}`);
+	const loadedModules = [];
+	for (const spec of specs) try {
+		const { declaration, AddonClass } = await loadAddonModule(spec.addonId, spec.addonDir);
+		loadedModules.push({
+			spec,
+			declaration,
+			AddonClass
+		});
+	} catch (err) {
+		console.error(`[addon-runner] Failed to load "${spec.addonId}": ${errMsg(err)}`);
+		process.exit(1);
+	}
+	let storageProvider;
+	let storageProviderError;
+	try {
+		const { FilesystemStorageProvider } = await import("@camstack/types/node");
+		storageProvider = new FilesystemStorageProvider(dataDir);
+	} catch (err) {
+		storageProviderError = err;
+	}
+	const INFRA_CAP_NAMES = new Set([
+		"settings-store",
+		"storage",
+		"log-destination",
+		"metrics-provider",
+		"platform-probe"
+	]);
+	const infraPriority = (decl) => {
+		const caps = decl.capabilities ?? [];
+		for (const cap of caps) {
+			const name = typeof cap === "string" ? cap : cap.name;
+			if (INFRA_CAP_NAMES.has(name)) return 0;
+		}
+		return 1;
+	};
+	loadedModules.sort((a, b) => infraPriority(a.declaration) - infraPriority(b.declaration));
+	/** UNION manifest accumulates one entry per addon as each initialises. */
+	const runnerManifest = [];
+	/**
+	* Aggregated singleton (system-scoped) providers across ALL addons in this
+	* runner — keyed by capName. Read by the UDS child-cap dispatch to resolve
+	* singleton calls (no Moleculer). Populated during the addon-init loop; a
+	* cap-call that arrives before its addon initialises is rejected by the
+	* dispatcher (the parent only routes caps the child has registered via the
+	* UDS `register`/`updateCaps` handshake).
+	*/
+	const allSingletonProviders = /* @__PURE__ */ new Map();
+	/**
+	* Per-addon route-provider map — keyed by addonId → the addon's live
+	* `addon-routes` provider object. Resolves `getRouteProvider(addonId)`
+	* per-addon rather than returning a single global provider. Populated
+	* during the init loop alongside `allSingletonProviders`.
+	*
+	* This is the correct abstraction even in the current single-addon-per-runner
+	* policy (D2/D9): it makes the lookup honest and future-safe for any explicit
+	* co-location scenario where two addons each declare `addon-routes`.
+	*/
+	const addonRouteProviders = /* @__PURE__ */ new Map();
+	/**
+	* Per-addon HTTP data-plane endpoints — keyed by addonId → the descriptors
+	* the addon's `ctx.dataPlane` facility published (via the `dataPlaneSink`
+	* passed into the context). Read by the UDS `target:'data-planes'` dispatch
+	* so the hub can pull them and set up its reverse-proxy. Mirrors
+	* `addonRouteProviders`.
+	*/
+	const addonDataPlanes = /* @__PURE__ */ new Map();
+	/**
+	* Per-addon instance map — keyed by addonId → the loaded addon instance.
+	* Backs the `settings` addon-call surface (`getAddonInstance`), which invokes
+	* the addon's global/device settings methods. Populated during the init loop;
+	* read lazily at call time (the dispatcher only fires after init completes).
+	*/
+	const loadedAddonInstances = /* @__PURE__ */ new Map();
+	/**
+	* Per-addon custom-action registry — populated during the init loop. Read by
+	* the UDS addon-call dispatch to resolve `target:'custom'` calls (mirrors the
+	* removed `custom.<action>` Moleculer action). Constructed up front so the
+	* addon-call handler can close over it at client-construction time.
+	*/
+	const customActionRegistry = new CustomActionRegistry();
+	let shuttingDown = false;
+	const udsChildClient = new LocalChildClient({
+		nodeId: parentNodeId,
+		childId: runnerId,
+		caps: buildChildCapDescriptors(runnerManifest, getWorkerNativeCapSnapshot()),
+		dispatch: createChildCapDispatch({
+			getSingletonProvider: (capName) => allSingletonProviders.get(capName) ?? null,
+			getDeviceProvider: (capName, deviceId) => getWorkerNativeCapProvider(capName, deviceId) ?? null
+		})
+	});
+	udsChildClient.onAddonCall(createChildAddonCallDispatch({
+		getRouteProvider: (addonId) => addonRouteProviders.get(addonId) ?? null,
+		customActions: customActionRegistry,
+		getAddonInstance: (addonId) => loadedAddonInstances.get(addonId) ?? null,
+		getDataPlanes: (addonId) => addonDataPlanes.get(addonId) ?? []
+	}));
+	const { logger: runnerLog, control: runnerLogControl } = createUdsLoggerWithControl(udsChildClient, runnerId, nodeId, "addon-runner");
+	udsChildClient.onSetLogLevel((level) => {
+		runnerLogControl.setLevel(level);
+		runnerLog.info(`Log level changed to "${level}" via UDS`);
+	});
+	try {
+		await udsChildClient.start();
+	} catch (err) {
+		console.error(`[addon-runner] "${nodeId}" UDS connect failed — exiting: ${errMsg(err)}`);
+		process.exit(1);
+	}
+	runnerLog.info("UDS child transport connected", { meta: { childId: runnerId } });
+	if (storageProvider) runnerLog.info(`"${nodeId}" storage provider rooted at ${dataDir}`);
+	else runnerLog.warn(`"${nodeId}" failed to load FilesystemStorageProvider`, { meta: { error: errMsg(storageProviderError) } });
+	const refreshChildCaps = (reason) => {
+		const freshDescriptors = buildChildCapDescriptors(runnerManifest, getWorkerNativeCapSnapshot());
+		udsChildClient.updateCaps(freshDescriptors).catch((err) => {
+			runnerLog.warn(`UDS updateCaps failed (${reason})`, { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+	};
+	let capRefreshTimer;
+	setWorkerNativeCapsChangeListener(() => {
+		if (capRefreshTimer !== void 0) return;
+		capRefreshTimer = setTimeout(() => {
+			capRefreshTimer = void 0;
+			refreshChildCaps("native-cap-change");
+		}, 200);
+		capRefreshTimer.unref?.();
+	});
+	const loaded = [];
+	const deviceRestorePromises = [];
+	for (const { spec, declaration, AddonClass } of loadedModules) try {
+		const addon = new AddonClass();
+		const context = await createUdsAddonContext(udsChildClient, nodeId, declaration, dataDir, {
+			...storageProvider ? { storageProvider } : {},
+			dataPlaneSink: { set: (addonId, endpoints) => {
+				addonDataPlanes.set(addonId, endpoints);
+			} }
+		});
+		await installManifestPythonDeps(declaration, spec.addonDir, context.deps, context.logger);
+		const registeredProviders = /* @__PURE__ */ new Map();
+		const initResult = normalizeAddonInitResult(await addon.initialize(context));
+		for (const reg of initResult?.providers ?? []) {
+			const capName = reg.capability.name;
+			registeredProviders.set(capName, reg.provider);
+			context.registerProvider(capName, reg.provider);
+			const prov = reg.provider;
+			if (prov !== null && typeof prov === "object" && !Array.isArray(prov)) {
+				allSingletonProviders.set(capName, prov);
+				if (capName === "addon-routes") addonRouteProviders.set(spec.addonId, prov);
+			}
+		}
+		if (initResult?.customActions && initResult.actionHandlers) {
+			const handlers = initResult.actionHandlers;
+			customActionRegistry.registerAddon(spec.addonId, initResult.customActions, (action, input) => {
+				const fn = handlers[action];
+				if (!fn) throw new Error(`addon '${spec.addonId}' has no handler for custom action '${action}'`);
+				return fn(input);
+			});
+		}
+		validateProviderRegistrations(spec.addonId, declaration, registeredProviders, context.logger);
+		const capNames = [...registeredProviders.keys()];
+		context.logger.info(`"${spec.addonId}" caps: ${capNames.length > 0 ? capNames.join(", ") : "(none)"}`);
+		runnerManifest.push({
+			addonId: spec.addonId,
+			capabilities: capNames
+		});
+		if (typeof addon.restoreDevices === "function") deviceRestorePromises.push(runWorkerDeviceRestoreWithRetry(addon, context, spec.addonId, nodeId));
+		addon.postBrokerStart();
+		loadedAddonInstances.set(spec.addonId, addon);
+		loaded.push({
+			addonId: spec.addonId,
+			declaration,
+			addon,
+			initResult: initResult ?? null
+		});
+	} catch (err) {
+		console.error(`[addon-runner] Init failed for "${spec.addonId}": ${errMsg(err)}`);
+		process.exit(1);
+	}
+	if (deviceRestorePromises.length > 0 && !shuttingDown) await Promise.allSettled(deviceRestorePromises);
+	refreshChildCaps("post-init");
+	let hubReachableFired = false;
+	const fireHubReachableOnce = () => {
+		if (hubReachableFired) return;
+		hubReachableFired = true;
+		for (const entry of loaded) if (typeof entry.addon.onHubReachable === "function") Promise.resolve(entry.addon.onHubReachable()).catch((err) => {
+			runnerLog.error(`"${entry.addonId}" onHubReachable() threw`, { meta: { error: errMsg(err) } });
+		});
+	};
+	udsChildClient.onConnected(() => {
+		if (hubReachableFired) refreshChildCaps("on reconnect");
+		fireHubReachableOnce();
+	});
+	fireHubReachableOnce();
+	runnerLog.info(`"${nodeId}" started — ${loaded.length} addon(s) ready (UDS connected)`);
+	process.stdout.write(`READY:${nodeId}\n`);
+	const shutdown = async () => {
+		shuttingDown = true;
+		setWorkerNativeCapsChangeListener(null);
+		if (capRefreshTimer !== void 0) {
+			clearTimeout(capRefreshTimer);
+			capRefreshTimer = void 0;
+		}
+		runnerLog.info(`"${nodeId}" shutting down ${loaded.length} addon(s)...`);
+		for (const entry of loaded) try {
+			await entry.addon.shutdown();
+		} catch (err) {
+			runnerLog.error(`"${entry.addonId}" shutdown threw`, { meta: { error: errMsg(err) } });
+		}
+		try {
+			await udsChildClient.close();
+		} catch (err) {
+			runnerLog.warn("UDS child transport close threw during shutdown", { meta: { error: errMsg(err) } });
+		}
+		process.exit(0);
+	};
+	process.on("SIGTERM", () => {
+		shutdown();
+	});
+	process.on("SIGINT", () => {
+		shutdown();
+	});
+	const initialPpid = process.ppid;
+	setInterval(() => {
+		if (process.ppid === 1 && initialPpid !== 1) {
+			console.error(`[addon-runner] "${nodeId}" parent died (reparented to init) — exiting`);
+			shutdown();
+		}
+	}, 5e3);
+}
+main().catch((err) => {
+	console.error(`[addon-runner] Fatal error: ${errMsg(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/auth/api-key-manager.d.ts

@@ -0,0 +1,26 @@
+import { AuthManager } from './auth-manager.js';
+import { ApiKeyRecord, SettingsStoreClient } from '@camstack/types';
+export type { ApiKeyRecord };
+interface CreateApiKeyInput {
+    label: string;
+    isAdmin?: boolean;
+    allowedProviders?: string[] | '*';
+    allowedDevices?: Record<string, string[] | '*'>;
+}
+export interface ApiKeyStorageAccess {
+    getStore(): SettingsStoreClient;
+}
+export declare class ApiKeyManager {
+    private readonly storageAccess;
+    private readonly auth;
+    constructor(storageAccess: ApiKeyStorageAccess, auth: AuthManager);
+    private get store();
+    create(input: CreateApiKeyInput): Promise<{
+        record: ApiKeyRecord;
+        token: string;
+    }>;
+    validateToken(token: string): Promise<ApiKeyRecord | null>;
+    listAll(): Promise<Omit<ApiKeyRecord, 'tokenHash'>[]>;
+    revoke(id: string): Promise<void>;
+    findById(id: string): Promise<ApiKeyRecord | null>;
+}