@camstack/server 0.2.2 → 1.0.1

package/dist/api/core/cap-providers.js

@@ -0,0 +1,1124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTEGRATION_CAP_MARKERS = void 0;
+exports.buildSystemProvider = buildSystemProvider;
+exports.buildNetworkQualityProvider = buildNetworkQualityProvider;
+exports.buildToastProvider = buildToastProvider;
+exports.computeTopology = computeTopology;
+exports.buildNodesProvider = buildNodesProvider;
+exports.buildIntegrationsProvider = buildIntegrationsProvider;
+exports.buildAddonsProvider = buildAddonsProvider;
+/* eslint-disable @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 800-line provider-factory module. The flagged sites delegate into Moleculer/EventBus/IntegrationRegistry surfaces typed as `unknown` to break circular dependencies; runtime contracts are validated by the cap-mount-helper layer above. Tracked separately. */
+/**
+ * Capability provider factories for the Phase E core caps —
+ * `system`, `network-quality`, `toast`, `nodes`, `integrations`,
+ * `addons`. Each factory builds a fresh provider object that
+ * fulfils the cap's `InferProvider<...>` contract by delegating
+ * to the existing backend services.
+ *
+ * Why factories instead of static singletons?
+ *   - `addons.custom` needs per-request `ctx.user` for per-action
+ *     auth checks. The cap-router codegen already passes `ctx`
+ *     into `getProvider(ctx)`, so closing over it is cheap and
+ *     keeps the auth surface tight.
+ *   - The other caps don't need ctx, but we keep the signature
+ *     uniform for symmetry.
+ *
+ * No addon "owns" these surfaces — they manage cluster state
+ * (cluster topology, integrations, addon packages) or expose
+ * server-level singletons (toast bus, network-quality tracker,
+ * feature flags + retention controls).
+ *
+ * Phase E (2026-05-06): replaces the hand-written core routers in
+ * `server/backend/src/api/core/{system,network-quality,toast,
+ * nodes,integrations,addons}.router.ts`.
+ */
+const os = __importStar(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const node_crypto_1 = require("node:crypto");
+const server_1 = require("@trpc/server");
+const types_1 = require("@camstack/types");
+const kernel_1 = require("@camstack/kernel");
+const integration_id_backfill_1 = require("../../boot/integration-id-backfill");
+const collection_preference_js_1 = require("./collection-preference.js");
+const bulk_update_coordinator_js_1 = require("./bulk-update-coordinator.js");
+const addon_package_service_js_1 = require("../../core/addon/addon-package.service.js");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+// ── system ──────────────────────────────────────────────────────────
+function getRetention(registry) {
+    return (registry?.getSingleton('analysis-data-persistence')?.retention ?? null);
+}
+function buildSystemProvider(feature, registry) {
+    return {
+        info: async () => feature.getManifest(),
+        health: async () => ({ status: 'ok', uptime: process.uptime() }),
+        featureFlags: async () => feature.getManifest(),
+        networkAddresses: async () => {
+            const ifaces = os.networkInterfaces();
+            const result = [];
+            for (const [name, addrs] of Object.entries(ifaces)) {
+                for (const addr of addrs ?? []) {
+                    result.push({
+                        name,
+                        address: addr.address,
+                        family: addr.family,
+                        internal: addr.internal,
+                    });
+                }
+            }
+            return result;
+        },
+        getRetentionConfig: async () => getRetention(registry)?.getConfig() ?? null,
+        setRetentionConfig: async (input) => {
+            getRetention(registry)?.setConfig(input);
+            return null;
+        },
+        forceRetentionCleanup: async () => {
+            await getRetention(registry)?.forceCleanup();
+        },
+    };
+}
+// ── network-quality ─────────────────────────────────────────────────
+function buildNetworkQualityProvider(nq) {
+    return {
+        getDeviceStats: async (input) => nq.getDeviceStats(input.deviceId),
+        getAllStats: async () => nq.getAllStats(),
+        reportClientStats: async (input) => {
+            nq.reportClientStats(input.deviceId, {
+                rttMs: input.rttMs,
+                jitterMs: input.jitterMs,
+                estimatedBandwidthKbps: input.estimatedBandwidthKbps,
+                packetLossPercent: input.packetLossPercent,
+            });
+        },
+    };
+}
+// ── toast ───────────────────────────────────────────────────────────
+//
+// Per-request factory: each subscription opens its own connectionId.
+// The factory captures `ctx.user.id` so the underlying ToastService
+// can scope deliveries (broadcast vs. per-user). The cap defines
+// `onToast` as a subscription — the codegen wires it through the
+// `iterableSubscription` adapter and pushes raw `Toast` payloads.
+function buildToastProvider(toastService, ctx) {
+    return {
+        onToast: (_input, push) => {
+            if (!toastService)
+                return () => { };
+            const userId = ctx.user?.id ?? 'anonymous';
+            const connectionId = (0, node_crypto_1.randomUUID)();
+            const unsubscribe = toastService.subscribe(connectionId, userId, (toast) => push(toast));
+            return unsubscribe ?? (() => { });
+        },
+    };
+}
+function getLocalIps() {
+    const interfaces = os.networkInterfaces();
+    const ips = [];
+    for (const ifaces of Object.values(interfaces)) {
+        if (!ifaces)
+            continue;
+        for (const iface of ifaces) {
+            if (iface.internal)
+                continue;
+            ips.push(iface.address);
+        }
+    }
+    return ips;
+}
+/**
+ * Pure (well, async) topology computation — same shape returned by the
+ * `nodes.topology` cap procedure. Extracted so the topology emitter
+ * service can produce identical snapshots without going through tRPC.
+ */
+async function computeTopology(agentRegistry, addonRegistry) {
+    const nodes = await agentRegistry.listNodes();
+    const allAddons = addonRegistry?.listAddons() ?? [];
+    const getInGroupAddonIds = (node) => {
+        const subs = (node.subProcesses ?? []);
+        return subs.flatMap((p) => p.addonIds ?? []);
+    };
+    const addonCaps = new Map();
+    for (const a of allAddons) {
+        const id = a.manifest?.id ?? '';
+        const caps = a.declaration?.capabilities?.map((c) => (typeof c === 'string' ? c : c.name)) ?? [];
+        addonCaps.set(id, caps);
+    }
+    const addonCategory = new Map();
+    for (const a of allAddons) {
+        const id = a.manifest?.id ?? '';
+        const category = a.declaration?.category ?? 'system';
+        addonCategory.set(id, category);
+    }
+    return nodes.map((node) => {
+        const inGroupAddonIds = new Set(getInGroupAddonIds(node));
+        const agentAddonIds = node.agentAddons ?? [];
+        const allNodeAddons = node.isHub
+            ? allAddons.map((a) => {
+                const id = a.manifest?.id ?? 'unknown';
+                return { id, capabilities: [...(addonCaps.get(id) ?? [])], status: 'running' };
+            })
+            : agentAddonIds.map((addonId) => ({
+                id: addonId,
+                capabilities: [...(addonCaps.get(addonId) ?? [])],
+                status: 'running',
+            }));
+        const inProcessAddons = allNodeAddons.filter((a) => !inGroupAddonIds.has(a.id));
+        const isolatedProcesses = (node.subProcesses ?? []);
+        const mainProcessServices = inProcessAddons.map((a) => ({
+            addonId: a.id,
+            capabilities: a.capabilities,
+            status: a.status,
+        }));
+        const mainProcess = node.isHub
+            ? {
+                pid: process.pid,
+                name: 'hub (core)',
+                state: 'running',
+                cpuPercent: node.status?.cpuPercent ?? 0,
+                memoryRss: process.memoryUsage().rss,
+                uptimeSeconds: Math.floor(process.uptime()),
+                services: mainProcessServices,
+            }
+            : {
+                pid: 0,
+                name: `${node.info.id} (core)`,
+                state: 'running',
+                cpuPercent: node.status?.cpuPercent ?? 0,
+                memoryRss: 0,
+                uptimeSeconds: Math.floor((Date.now() - node.connectedSince) / 1000),
+                services: mainProcessServices,
+            };
+        const childProcesses = isolatedProcesses.map((p) => {
+            const memberIds = p.addonIds && p.addonIds.length > 0 ? p.addonIds : [p.name];
+            return {
+                pid: p.pid,
+                name: p.name,
+                state: p.state,
+                cpuPercent: p.cpuPercent,
+                memoryRss: p.memoryRss,
+                uptimeSeconds: p.uptimeSeconds,
+                groupId: p.groupId ?? p.name,
+                services: memberIds.map((addonId) => ({
+                    addonId,
+                    capabilities: [...(addonCaps.get(addonId) ?? [])],
+                    status: p.state,
+                })),
+            };
+        });
+        // Aggregate node-local addons by category. `allNodeAddons` already
+        // contains the per-node addon roster (hub uses every installed
+        // addon; agents use their assigned agentAddons subset).
+        const byCategory = new Map();
+        const procByAddon = new Map();
+        for (const p of (node.subProcesses ?? [])) {
+            for (const addonId of p.addonIds ?? []) {
+                procByAddon.set(addonId, {
+                    cpuPercent: p.cpuPercent,
+                    memoryRss: p.memoryRss,
+                    state: p.state,
+                });
+            }
+        }
+        for (const a of allNodeAddons) {
+            const category = addonCategory.get(a.id) ?? 'system';
+            const procInfo = procByAddon.get(a.id);
+            const entry = byCategory.get(category) ?? { category, total: 0, healthy: 0, addons: [] };
+            const status = procInfo?.state ?? a.status;
+            entry.total += 1;
+            if (status === 'running')
+                entry.healthy += 1;
+            entry.addons.push({
+                id: a.id,
+                status,
+                cpuPercent: procInfo?.cpuPercent ?? 0,
+                memoryRss: procInfo?.memoryRss ?? 0,
+            });
+            byCategory.set(category, entry);
+        }
+        const categoriesProjection = [...byCategory.values()];
+        return {
+            id: node.info.id,
+            name: node.info.name,
+            hostname: node.isHub ? os.hostname() : (node.info.hostname ?? node.info.id),
+            platform: node.info.platform ?? 'unknown',
+            arch: node.info.arch ?? 'unknown',
+            cpuModel: node.info.cpuModel ?? null,
+            cpuCores: node.info.cpuCores ?? 0,
+            memoryMB: node.info.memoryMB ?? 0,
+            engines: [...(node.info.pythonRuntimes ?? [])],
+            isHub: node.isHub,
+            isOnline: node.isOnline !== false,
+            cpuPercent: node.status?.cpuPercent ?? 0,
+            memoryPercent: node.status?.memoryPercent ?? 0,
+            uptime: Date.now() - node.connectedSince,
+            lastSeen: new Date().toISOString(),
+            localIps: node.isHub ? getLocalIps() : (node.localIps ?? []),
+            addons: allNodeAddons,
+            processes: [mainProcess, ...childProcesses],
+            categories: categoriesProjection,
+        };
+    });
+}
+function buildNodesProvider(agentRegistry, moleculer, addonRegistry) {
+    const broker = moleculer.broker;
+    return {
+        topology: async () => computeTopology(agentRegistry, addonRegistry),
+        deployAddon: async () => {
+            // Placeholder — actual deployment orchestration TBD
+            return { success: true };
+        },
+        undeployAddon: async (input) => {
+            await broker.call('$agent.undeploy', {
+                addonId: input.addonId,
+            }, { nodeID: input.nodeId, timeout: 30_000 });
+            return { success: true };
+        },
+        restartAddon: async (input) => {
+            const isHubLocal = input.nodeId === 'hub' || input.nodeId.startsWith('hub/');
+            if (isHubLocal && addonRegistry) {
+                const result = await addonRegistry.restartAddon(input.addonId);
+                if (typeof result === 'object' && result !== null && 'success' in result) {
+                    return result;
+                }
+                return { success: true };
+            }
+            const agentNodeId = input.nodeId.includes('/') ? input.nodeId.split('/')[0] : input.nodeId;
+            await broker.call('$agent.restart', {
+                addonId: input.addonId,
+            }, { nodeID: agentNodeId, timeout: 30_000 });
+            return { success: true };
+        },
+        restartProcess: async (input) => {
+            return (await broker.call('$process.restart', {
+                name: input.processName,
+            }, { nodeID: input.nodeId, timeout: 30_000 }));
+        },
+        restartNode: async (input) => {
+            return (await broker.call('$process.restartAll', {}, {
+                nodeID: input.nodeId,
+                timeout: 60_000,
+            }));
+        },
+        shutdownNode: async (input) => {
+            if (input.nodeId === 'hub') {
+                setTimeout(() => process.exit(0), 500);
+                return { success: true };
+            }
+            await broker.call('$agent.shutdown', {}, {
+                nodeID: input.nodeId,
+                timeout: 10_000,
+            });
+            return { success: true };
+        },
+        renameNode: async (input) => {
+            const trimmed = input.name.trim();
+            if (input.nodeId === 'hub') {
+                const key = `node-display-name:${input.nodeId}`;
+                await broker.call('settings-store.set', {
+                    collection: 'system-settings',
+                    key,
+                    value: trimmed,
+                });
+            }
+            else {
+                await broker.call('$agent.rename', {
+                    name: trimmed,
+                }, { nodeID: input.nodeId, timeout: 10_000 });
+                agentRegistry.updateAgentName(input.nodeId, trimmed);
+            }
+            return { nodeId: input.nodeId, name: trimmed };
+        },
+        getNodeAddons: async (input) => {
+            // Hub branch: read straight from the local registry. Surfaces every
+            // loaded addon with its package name + version so the per-node Addons
+            // tab can render the same shape regardless of whether the target is
+            // hub or agent.
+            if (input.nodeId === 'hub') {
+                const rows = addonRegistry?.listAddons() ?? [];
+                return rows.map((r) => ({
+                    id: r.manifest.id,
+                    status: r.process?.state ?? 'running',
+                    version: r.manifest.packageVersion,
+                    packageName: r.manifest.packageName,
+                }));
+            }
+            // Agent branch: forward to `$agent.status` and pick out its `addons`
+            // field. Done as a direct call (not via `agentRegistry`'s cached
+            // listing) so the UI always sees fresh data when it opens the tab
+            // — the cache otherwise lags the cluster heartbeat interval.
+            try {
+                const status = await broker.call('$agent.status', {}, { nodeID: input.nodeId, timeout: 5_000 });
+                return (status.addons ?? []).map((a) => ({
+                    id: a.id,
+                    status: a.status,
+                    ...(a.version !== undefined ? { version: a.version } : {}),
+                    ...(a.packageName !== undefined ? { packageName: a.packageName } : {}),
+                }));
+            }
+            catch {
+                return [];
+            }
+        },
+        clusterAddonStatus: async () => {
+            const hubAddons = addonRegistry?.listAllAddons() ?? [];
+            const hubMap = new Map(hubAddons.map((a) => [a.manifest.id, a]));
+            const nodes = await agentRegistry.listNodes();
+            const remoteNodes = nodes.filter((n) => !n.isHub && n.connectedSince > 0);
+            const remoteStatuses = await Promise.all(remoteNodes.map(async (node) => {
+                try {
+                    const status = (await broker.call('$agent.status', {}, {
+                        nodeID: node.info.id,
+                        timeout: 5_000,
+                    }));
+                    return {
+                        nodeId: node.info.id,
+                        name: node.info.name,
+                        online: true,
+                        addons: status.addons ?? [],
+                    };
+                }
+                catch {
+                    return {
+                        nodeId: node.info.id,
+                        name: node.info.name,
+                        online: false,
+                        addons: [],
+                    };
+                }
+            }));
+            const result = {};
+            for (const [addonId, hubAddon] of hubMap) {
+                const hubVersion = hubAddon.manifest.packageVersion;
+                const addonNodes = [
+                    { nodeId: 'hub', name: 'hub', version: hubVersion, status: 'running', synced: true },
+                ];
+                for (const remote of remoteStatuses) {
+                    const remoteAddon = remote.addons.find((a) => a.id === addonId);
+                    if (remoteAddon) {
+                        const remoteVersion = remoteAddon.version ?? 'unknown';
+                        addonNodes.push({
+                            nodeId: remote.nodeId,
+                            name: remote.name,
+                            version: remoteVersion,
+                            status: remote.online ? remoteAddon.status : 'offline',
+                            synced: remoteVersion === hubVersion,
+                        });
+                    }
+                }
+                result[addonId] = { hubVersion, nodes: addonNodes };
+            }
+            return result;
+        },
+        getCapUsageGraph: async (input) => {
+            const reg = (0, kernel_1.getCapUsageRegistry)();
+            return reg.getGraph({ windowSeconds: input.windowSeconds, nowMs: Date.now() });
+        },
+        setProcessLogLevel: async (input) => {
+            // E2: for hub-local children, try the UDS path first (fire-and-forget);
+            // fall back to the Moleculer $node-mgmt.setLogLevel action for remote
+            // nodes (agents) that still run a per-node broker. The UDS path is always
+            // attempted for hub/<runner> nodeIds even when the Moleculer path would
+            // also work — both are safe to run in parallel during Phase E.
+            const reachedViaUds = moleculer.setChildLogLevelByNodeId(input.nodeId, input.level);
+            if (!reachedViaUds) {
+                await broker.call('$node-mgmt.setLogLevel', {
+                    level: input.level,
+                }, { nodeID: input.nodeId, timeout: 5_000 });
+            }
+            return { success: true };
+        },
+        executeQuery: async (input) => {
+            return await broker.call(`${input.addonId}.queryable.query`, { queryName: input.queryName, params: input.params ?? {} }, { nodeID: input.nodeId, timeout: 30_000 });
+        },
+    };
+}
+function requireIntegrationRegistry(ar) {
+    const reg = ar.getIntegrationRegistry();
+    if (!reg)
+        throw new Error('IntegrationRegistry not available');
+    return reg;
+}
+function isDeviceProvider(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'discoverDevices') === 'function');
+}
+function getDeviceProvider(ar, addonId) {
+    const provider = ar.getCapabilityRegistry().getProviderByAddon('device-provider', addonId);
+    return isDeviceProvider(provider) ? provider : null;
+}
+/**
+ * Marker caps that flag an addon as a creatable integration type:
+ *   - `device-provider` — classic providers (Reolink/ONVIF/Frigate)
+ *     that expose `createDevice` + `discoverDevices` via their
+ *     device-provider cap.
+ *   - `device-adoption` — integration-style providers (Home Assistant
+ *     and future siblings) that materialise devices via a generic
+ *     adoption cap instead of a manual create-form. The picker treats
+ *     them the same way; the wizard's discovery step routes through the
+ *     specific cap based on the addon's declared surface.
+ *
+ * Exported so the integration-markers spec can assert the recognised set
+ * without booting the whole provider factory.
+ */
+exports.INTEGRATION_CAP_MARKERS = new Set(['device-provider', 'device-adoption']);
+function buildIntegrationsProvider(ar, eb, loggingService, capabilityRegistry) {
+    const logger = loggingService.createLogger('integrations');
+    const withProcessState = (i) => ({
+        ...i,
+        processState: ar.listAddons().find((a) => a.manifest.id === i.addonId)?.process?.state ?? 'unknown',
+    });
+    return {
+        list: async () => {
+            const integrations = await requireIntegrationRegistry(ar).listIntegrations();
+            return integrations.map(withProcessState);
+        },
+        get: async (input) => {
+            const integration = await requireIntegrationRegistry(ar).getIntegration(input.id);
+            if (!integration)
+                throw new Error(`Integration "${input.id}" not found`);
+            return withProcessState(integration);
+        },
+        getByAddonId: async (input) => requireIntegrationRegistry(ar).getIntegrationByAddonId(input.addonId),
+        create: async (input) => {
+            const { skipRestart, ...payload } = input;
+            const reg = requireIntegrationRegistry(ar);
+            logger.info('request', {
+                tags: { addonId: input.addonId },
+                meta: { phase: 'create', name: input.name },
+            });
+            const addon = ar.listAddons().find((a) => a.manifest.id === input.addonId);
+            const instanceMode = addon?.declaration?.instanceMode ?? addon?.manifest?.instanceMode ?? 'multiple';
+            if (instanceMode === 'unique') {
+                const existing = (await reg.listIntegrations()).filter((i) => i.addonId === input.addonId);
+                if (existing.length > 0) {
+                    logger.warn('rejected duplicate unique', {
+                        tags: { addonId: input.addonId, integrationId: existing[0].id },
+                        meta: { phase: 'create' },
+                    });
+                    throw new Error(`Addon "${input.addonId}" is unique-instance and already has an integration (${existing[0].id})`);
+                }
+            }
+            const integration = await reg.createIntegration(payload);
+            logger.info('persisted', {
+                tags: { integrationId: integration.id, addonId: integration.addonId },
+                meta: { phase: 'create' },
+            });
+            const hasSettings = input.settings != null && Object.keys(input.settings).length > 0;
+            if (!skipRestart && hasSettings) {
+                logger.info('settings present — restarting addon', {
+                    tags: { addonId: input.addonId },
+                    meta: { phase: 'create' },
+                });
+                await ar.restartAddon(input.addonId);
+                logger.info('addon restart complete', {
+                    tags: { addonId: input.addonId },
+                    meta: { phase: 'create' },
+                });
+            }
+            else {
+                logger.info('skipping restart (no settings or skipRestart=true)', {
+                    meta: { phase: 'create' },
+                });
+            }
+            return integration;
+        },
+        update: async (input) => {
+            const reg = requireIntegrationRegistry(ar);
+            const previous = await reg.getIntegration(input.id);
+            if (!previous) {
+                logger.warn('not found', { tags: { integrationId: input.id }, meta: { phase: 'update' } });
+                throw new Error(`Integration "${input.id}" not found`);
+            }
+            const { id, ...updates } = input;
+            const changedFields = Object.keys(updates).filter((k) => updates[k] !== undefined);
+            logger.info('request', {
+                tags: { integrationId: input.id, addonId: previous.addonId },
+                meta: { phase: 'update', fields: changedFields },
+            });
+            const result = await reg.updateIntegration(id, updates);
+            if (!result)
+                throw new Error(`Integration "${id}" not found`);
+            const enabledChanged = input.enabled !== undefined && input.enabled !== previous.enabled;
+            if (enabledChanged) {
+                const category = input.enabled ? 'integration.enabled' : 'integration.disabled';
+                logger.info('enabled state changed', {
+                    tags: { integrationId: result.id, addonId: result.addonId },
+                    meta: { phase: 'update', enabled: input.enabled },
+                });
+                eb.emit({
+                    id: `integration-${category}-${Date.now()}`,
+                    timestamp: new Date(),
+                    source: { type: 'integration', id: result.id },
+                    category,
+                    data: {
+                        integrationId: result.id,
+                        addonId: result.addonId,
+                    },
+                });
+            }
+            if (input.name !== undefined && input.name !== previous.name) {
+                logger.info('renamed', {
+                    tags: { integrationId: result.id },
+                    meta: { phase: 'update', previousName: previous.name, newName: input.name },
+                });
+            }
+            const infoChanged = input.info !== undefined;
+            if (infoChanged) {
+                logger.info('info changed — restarting addon', {
+                    tags: { addonId: result.addonId },
+                    meta: { phase: 'update' },
+                });
+                await ar.restartAddon(result.addonId);
+                logger.info('addon restart complete', {
+                    tags: { addonId: result.addonId },
+                    meta: { phase: 'update' },
+                });
+            }
+            else {
+                logger.info('no restart needed (only enabled/name changed)', { meta: { phase: 'update' } });
+            }
+            return result;
+        },
+        delete: async (input) => {
+            const reg = requireIntegrationRegistry(ar);
+            logger.info('request', { tags: { integrationId: input.id }, meta: { phase: 'delete' } });
+            const integration = await reg.getIntegration(input.id);
+            if (!integration) {
+                logger.warn('not found', { tags: { integrationId: input.id }, meta: { phase: 'delete' } });
+                throw new Error(`Integration "${input.id}" not found`);
+            }
+            logger.info('removing', {
+                tags: { integrationId: input.id, addonId: integration.addonId },
+                meta: { phase: 'delete', name: integration.name },
+            });
+            // Cascade-delete every live device whose integrationId matches.
+            // Best-effort: a device-removal hiccup must not abort the integration
+            // delete — log a warning and continue so the record + event always fire.
+            const dm = capabilityRegistry?.getSingleton('device-manager') ?? null;
+            // Claim legacy un-tagged devices BEFORE the cascade. Devices created
+            // before stamping (or whose provider never stamps, e.g. `provider-rtsp`)
+            // carry no integrationId, so `removeByIntegration` (which matches on
+            // integrationId) would leave them orphaned forever once their integration
+            // is gone. While the integration record still exists, stamp the
+            // unambiguous ones (addons hosting exactly one integration) so the cascade
+            // below removes them too. Best-effort: never abort the delete.
+            if (dm?.listAll && dm?.setIntegrationId) {
+                try {
+                    const [integrations, devices] = await Promise.all([
+                        reg.listIntegrations(),
+                        dm.listAll({}),
+                    ]);
+                    const stamps = (0, integration_id_backfill_1.planDeleteTimeStamps)(input.id, integrations.map((i) => ({ id: i.id, addonId: i.addonId })), devices.map((d) => ({
+                        id: d.id,
+                        addonId: d.addonId,
+                        parentDeviceId: d.parentDeviceId,
+                        ...(d.integrationId !== undefined ? { integrationId: d.integrationId } : {}),
+                    })));
+                    for (const stamp of stamps) {
+                        await dm.setIntegrationId({
+                            deviceId: stamp.deviceId,
+                            integrationId: stamp.integrationId,
+                        });
+                    }
+                    if (stamps.length > 0) {
+                        logger.info('claimed legacy un-tagged devices for cascade', {
+                            tags: { integrationId: input.id, addonId: integration.addonId },
+                            meta: { phase: 'delete', claimed: stamps.length },
+                        });
+                    }
+                }
+                catch (err) {
+                    logger.warn('legacy device claim failed (best-effort — continuing)', {
+                        tags: { integrationId: input.id },
+                        meta: { phase: 'delete', error: (0, types_1.errMsg)(err) },
+                    });
+                }
+            }
+            if (dm?.removeByIntegration) {
+                try {
+                    const result = await dm.removeByIntegration({ integrationId: input.id });
+                    logger.info('cascade-removed devices', {
+                        tags: { integrationId: input.id },
+                        meta: { phase: 'delete', removed: result.removed },
+                    });
+                }
+                catch (err) {
+                    logger.warn('device cascade-remove failed (best-effort — continuing)', {
+                        tags: { integrationId: input.id },
+                        meta: { phase: 'delete', error: (0, types_1.errMsg)(err) },
+                    });
+                }
+            }
+            else {
+                logger.warn('device-manager not available — skipping cascade device removal', {
+                    tags: { integrationId: input.id },
+                    meta: { phase: 'delete' },
+                });
+            }
+            await reg.deleteIntegration(input.id);
+            eb.emit({
+                id: `integration-deleted-${Date.now()}`,
+                timestamp: new Date(),
+                source: { type: 'integration', id: input.id },
+                category: types_1.EventCategory.IntegrationDeleted,
+                data: {
+                    integrationId: input.id,
+                    addonId: integration.addonId,
+                },
+            });
+            logger.info('completed (no restart)', {
+                tags: { integrationId: input.id },
+                meta: { phase: 'delete' },
+            });
+            return { success: true, deletedId: input.id };
+        },
+        getSettings: async (input) => {
+            const reg = requireIntegrationRegistry(ar);
+            const integration = await reg.getIntegration(input.id);
+            if (!integration)
+                throw new Error(`Integration "${input.id}" not found`);
+            return reg.getIntegrationSettings(input.id);
+        },
+        setSettings: async (input) => {
+            const reg = requireIntegrationRegistry(ar);
+            const integration = await reg.getIntegration(input.id);
+            if (!integration) {
+                logger.warn('not found', {
+                    tags: { integrationId: input.id },
+                    meta: { phase: 'setSettings' },
+                });
+                throw new Error(`Integration "${input.id}" not found`);
+            }
+            const settingsKeys = Object.keys(input.settings);
+            logger.info('request', {
+                tags: { integrationId: input.id, addonId: integration.addonId },
+                meta: { phase: 'setSettings', keys: settingsKeys },
+            });
+            await reg.setIntegrationSettings(input.id, input.settings);
+            logger.info('persisted — restarting addon', {
+                tags: { addonId: integration.addonId },
+                meta: { phase: 'setSettings' },
+            });
+            await ar.restartAddon(integration.addonId);
+            logger.info('addon restart complete', {
+                tags: { addonId: integration.addonId },
+                meta: { phase: 'setSettings' },
+            });
+            return { success: true };
+        },
+        getAvailableTypes: async () => {
+            const reg = requireIntegrationRegistry(ar);
+            const addons = ar.listAddons();
+            // Hide failed-to-load packages from the picker. Fix #7 surfaces them in
+            // the Addons page so the operator can uninstall, but creating an
+            // integration against an addon that didn't load produces an orphaned
+            // row that `createFilteredRegistry` then filters out — silent data
+            // loss from the operator's POV. Filter at the source instead.
+            //
+            // Markers that flag an addon as a creatable integration type live
+            // in the module-level `INTEGRATION_CAP_MARKERS` set (exported so the
+            // integration-markers spec can assert the recognised caps).
+            const providerAddons = addons.filter((a) => a.process?.state !== 'failed' &&
+                a.manifest.capabilities?.some((c) => {
+                    const name = typeof c === 'string' ? c : c.name;
+                    return typeof name === 'string' && exports.INTEGRATION_CAP_MARKERS.has(name);
+                }));
+            const integrations = await reg.listIntegrations();
+            return providerAddons.map((addon) => {
+                const m = addon.manifest;
+                const d = addon.declaration;
+                const icon = d?.icon ?? m.icon;
+                const color = d?.color ?? m.color ?? '#78716c';
+                const instanceMode = d?.instanceMode ?? m.instanceMode ?? 'multiple';
+                const existing = integrations.filter((i) => i.addonId === m.id);
+                const provider = getDeviceProvider(ar, m.id);
+                const discoveryMode = provider?.discoveryMode ?? 'manual';
+                // Branch by CAP, not by addon name. Surface which integration-marker
+                // cap the addon declared so the wizard routes `device-adoption`
+                // (Approach A: pick/create a broker, store `{ brokerId }`) vs the
+                // legacy `device-provider` config → discovery flow. A `device-adoption`
+                // marker wins when both are present (an integration-style addon may
+                // also expose a `device-provider` shim); the broker step is the
+                // intended entry point for it.
+                const capNames = (m.capabilities ?? []).map((c) => (typeof c === 'string' ? c : c.name));
+                const kind = capNames.includes('device-adoption')
+                    ? 'device-adoption'
+                    : 'device-provider';
+                // For device-adoption addons, the broker kind to create/link comes
+                // from the addon manifest (`brokerKind`). Null for device-provider
+                // addons, which carry no broker.
+                const brokerKind = kind === 'device-adoption' ? (d?.brokerKind ?? m.brokerKind ?? null) : null;
+                const supportsLocationImport = kind === 'device-adoption'
+                    ? (d?.supportsLocationImport ?? m.supportsLocationImport ?? false)
+                    : false;
+                return {
+                    addonId: m.id,
+                    name: m.name ?? m.id,
+                    description: m.description ?? '',
+                    iconUrl: icon ? `/api/addon-assets/${m.id}/${icon}` : null,
+                    color,
+                    instanceMode,
+                    discoveryMode,
+                    kind,
+                    brokerKind,
+                    supportsLocationImport,
+                    existingInstances: existing.map((i) => ({
+                        id: i.id,
+                        name: i.name,
+                    })),
+                    canAdd: instanceMode === 'multiple' || existing.length === 0,
+                };
+            });
+        },
+        testConnection: async (input) => {
+            // Broker-backed integrations (Approach A) carry their connection
+            // identity as a `brokerId` in settings — testing is a broker
+            // concern now, so delegate to the addon's `broker` cap. The broker
+            // already owns the real semantic check (HA opens a temporary WS
+            // handshake; MQTT pings the bridge). We translate the broker's
+            // discriminated result (`{ok:true,latencyMs}|{ok:false,error}`) into
+            // the integrations `{success, error?}` output shape. Falls back to
+            // the default RTSP/ffprobe path below for legacy device-provider
+            // addons (Reolink/Frigate/ONVIF) that probe a stream URL.
+            const registry = ar.getCapabilityRegistry();
+            const brokerId = input.settings['brokerId'];
+            if (typeof brokerId === 'string' && brokerId.length > 0) {
+                const brokerProvider = registry.getProviderByAddonId('broker', input.addonId);
+                if (!brokerProvider) {
+                    return {
+                        success: false,
+                        error: `Broker provider for addon '${input.addonId}' is not available`,
+                    };
+                }
+                try {
+                    const result = await brokerProvider.testConnection({ id: brokerId });
+                    return result.ok ? { success: true } : { success: false, error: result.error };
+                }
+                catch (err) {
+                    return { success: false, error: (0, types_1.errMsg)(err) };
+                }
+            }
+            // Default — RTSP/Frigate/ONVIF legacy path: probe the stream URL.
+            const url = String(input.settings['main_stream_url'] ?? input.settings['url'] ?? '').trim();
+            if (!url)
+                return { success: false, error: 'No stream URL provided' };
+            try {
+                const { stdout } = await execFileAsync('ffprobe', [
+                    '-v',
+                    'error',
+                    '-rtsp_transport',
+                    'tcp',
+                    '-timeout',
+                    '3000000',
+                    '-show_entries',
+                    'stream=codec_name,width,height',
+                    '-of',
+                    'json',
+                    url,
+                ], { timeout: 5000 });
+                const parsed = (0, types_1.asJsonObject)(JSON.parse(stdout));
+                const streams = (0, types_1.asJsonArray)(parsed?.streams);
+                return streams.length > 0
+                    ? { success: true }
+                    : { success: false, error: 'No streams found at URL' };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Connection failed: ${(0, types_1.errMsg)(err)}`,
+                };
+            }
+        },
+    };
+}
+// ── addons ──────────────────────────────────────────────────────────
+//
+// `addons.custom` enforces per-action auth dynamically. The cap-router
+// codegen passes ctx into `getProvider(ctx)` so we can close over
+// `ctx.user` and reject before dispatching.
+function ensureCustomActionAuth(ctx, level) {
+    if (level === 'public')
+        return;
+    if (!ctx.user) {
+        throw new server_1.TRPCError({ code: 'UNAUTHORIZED' });
+    }
+    if (level === 'protected')
+        return;
+    if (level === 'admin') {
+        if (!ctx.user.isAdmin) {
+            throw new server_1.TRPCError({ code: 'FORBIDDEN', message: 'custom action requires admin' });
+        }
+        return;
+    }
+}
+/** A node id that refers to the hub itself (top-level or a hub group runner). */
+function isHubNode(nodeId) {
+    return nodeId === 'hub' || nodeId.startsWith('hub/');
+}
+/**
+ * Read an agent's installed npm packages via `$agent.status`. The
+ * agent reports its addon roster (id + status + version + packageName);
+ * we keep only entries that carry both a package name and a version so
+ * the hub can diff them against npm.
+ */
+async function fetchAgentInstalledPackages(broker, nodeId) {
+    const status = await broker.call('$agent.status', {}, { nodeID: nodeId, timeout: 5_000 });
+    const out = [];
+    for (const a of status.addons ?? []) {
+        if (typeof a.packageName === 'string' && typeof a.version === 'string') {
+            out.push({ name: a.packageName, version: a.version });
+        }
+    }
+    return out;
+}
+function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, eb) {
+    const broker = moleculer.broker;
+    // Adapt the hub EventBusService (which takes a full SystemEvent object) to
+    // the IBulkUpdateEventBus interface (which takes (category, payload) pairs).
+    // Using `import { EventCategory }` from @camstack/types avoids a new import
+    // — it is already resolved in the generated-cap-routers layer above. The
+    // `eb.emit` overload that takes a TypedSystemEvent is the type-safe path.
+    const bulkEventBus = {
+        emit: (category, payload) => {
+            eb.emit({
+                id: (0, node_crypto_1.randomUUID)(),
+                timestamp: new Date(),
+                source: { type: 'core', id: 'bulk-update-coordinator' },
+                category,
+                data: payload,
+            });
+        },
+    };
+    const bulkCoordinator = new bulk_update_coordinator_js_1.BulkUpdateCoordinator({
+        eventBus: bulkEventBus,
+        updateAddon: async (i) => {
+            await ps.updatePackage(i.name, i.version);
+        },
+        updateFrameworkPackage: async (i) => {
+            await ps.updateFrameworkPackage({
+                packageName: i.packageName,
+                version: i.version,
+                deferRestart: i.deferRestart,
+            });
+        },
+        restartServer: async () => {
+            await ps.restartServer(ctx.user?.username ?? ctx.user?.id);
+        },
+        logger: ls.createLogger('bulk-update'),
+    });
+    const frameworkAllowSet = new Set(addon_package_service_js_1.FRAMEWORK_PACKAGE_ALLOWLIST);
+    return {
+        list: async () => {
+            const rollbackable = ps.getRollbackablePackages();
+            const healthByPackage = new Map();
+            for (const h of ar.getAddonHealthSnapshot()) {
+                healthByPackage.set(h.packageName, h);
+            }
+            return ar.listAllAddons().map((item) => ({
+                ...item,
+                hasBackup: rollbackable.has(item.manifest.packageName),
+                health: healthByPackage.get(item.manifest.packageName) ?? null,
+            }));
+        },
+        getLogs: async (input) => ls.query({
+            tags: { addonId: input.addonId },
+            limit: input.limit,
+            level: input.level,
+        }),
+        listPackages: async () => ps.listInstalled(),
+        installPackage: async (input) => ps.installAndLoad(input.packageName, input.version),
+        installFromWorkspace: async (input) => ps.installFromWorkspaceAndLoad(input.packageName),
+        isWorkspaceAvailable: async () => ps.isWorkspaceAvailable(),
+        listWorkspacePackages: async () => ps.listWorkspacePackages(),
+        uninstallPackage: async (input) => ps.uninstallAndReload(input.packageName),
+        reloadPackages: async () => ps.reloadPackages(),
+        searchAvailable: async (input) => {
+            const results = await ps.searchNpm(input?.query);
+            const installedIds = new Set(ps.listInstalled().map((p) => p.name));
+            return results.map((r) => ({
+                ...r,
+                installed: installedIds.has(r.name),
+            }));
+        },
+        listUpdates: async (input) => {
+            const nodeId = input.nodeId;
+            const updates = nodeId === undefined || isHubNode(nodeId)
+                ? await ps.checkUpdates()
+                : await ps.checkUpdatesForInstalled(await fetchAgentInstalledPackages(broker, nodeId));
+            return updates.map((u) => ({ ...u, isSystem: frameworkAllowSet.has(u.name) }));
+        },
+        updatePackage: async (input) => {
+            const nodeId = input.nodeId;
+            if (nodeId === undefined || isHubNode(nodeId)) {
+                return ps.updatePackage(input.name, input.version);
+            }
+            // Agent target: the hub packs the resolved version and ships the
+            // tarball over `$agent.deploy` — the agent has no npm runtime.
+            const packed = await ps.packPackage(input.name, input.version);
+            await broker.call('$agent.deploy', { addonId: input.name, bundle: packed.buffer }, { nodeID: nodeId, timeout: 120_000 });
+            await broker.call('$agent.reload', {}, { nodeID: nodeId, timeout: 120_000 });
+            return { success: true, name: input.name, version: packed.version, nodeId };
+        },
+        rollbackPackage: async (input) => ps.rollbackPackage(input.name),
+        forceRefresh: async (input) => {
+            const nodeId = input.nodeId;
+            if (nodeId === undefined || isHubNode(nodeId))
+                return ps.checkUpdates(true);
+            // Agent rosters carry no hub-side cache — the diff is always live.
+            const installed = await fetchAgentInstalledPackages(broker, nodeId);
+            return ps.checkUpdatesForInstalled(installed);
+        },
+        restartServer: async () => ps.restartServer(ctx.user?.username ?? ctx.user?.id),
+        getLastRestart: async () => {
+            // Avoid pulling PostBootService through the cap-providers tree —
+            // dynamic import keeps the wiring loose and lets us read the
+            // static cache without a constructor dependency.
+            const mod = await Promise.resolve().then(() => __importStar(require('../../boot/post-boot.service.js')));
+            return mod.PostBootService.getLastRestart();
+        },
+        listFrameworkPackages: async () => ps.listFrameworkPackages(),
+        listCapabilityProviders: async (input) => {
+            const registry = ar.getCapabilityRegistry();
+            const caps = registry.listCapabilities();
+            const found = caps.find((c) => c.name === input.capName);
+            if (!found)
+                return [];
+            const mode = found.mode === 'collection' ? 'collection' : 'singleton';
+            const disabled = new Set(found.disabledProviders);
+            return found.providers.map((addonId) => ({
+                addonId,
+                mode,
+                isActive: mode === 'collection' ? !disabled.has(addonId) : found.activeProvider === addonId,
+            }));
+        },
+        setCapabilityProviderEnabled: async (input) => {
+            const registry = ar.getCapabilityRegistry();
+            const caps = registry.listCapabilities();
+            const found = caps.find((c) => c.name === input.capName);
+            if (!found) {
+                throw new server_1.TRPCError({
+                    code: 'NOT_FOUND',
+                    message: `Unknown capability: ${input.capName}`,
+                });
+            }
+            if (found.mode !== 'collection') {
+                throw new server_1.TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: `Capability "${input.capName}" is not a collection`,
+                });
+            }
+            if (!found.providers.includes(input.addonId)) {
+                throw new server_1.TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: `Provider "${input.addonId}" is not registered for "${input.capName}"`,
+                });
+            }
+            if (input.enabled) {
+                registry.enableCollectionProvider(input.capName, input.addonId);
+            }
+            else {
+                registry.disableCollectionProvider(input.capName, input.addonId);
+            }
+            // Persist the new disabled-set so the choice survives a hub reboot.
+            // Reuses the same `capabilities.collection.<cap>` key/format the
+            // `capabilities` core router writes — via the shared canonical writer.
+            const updated = registry.listCapabilities().find((c) => c.name === input.capName);
+            (0, collection_preference_js_1.persistCollectionDisabled)(configService, input.capName, updated?.disabledProviders ?? []);
+            return { success: true };
+        },
+        updateFrameworkPackage: async (input) => ps.updateFrameworkPackage({
+            packageName: input.packageName,
+            ...(input.version !== undefined ? { version: input.version } : {}),
+            ...(ctx.user?.username !== undefined
+                ? { requestedBy: ctx.user.username }
+                : ctx.user?.id !== undefined
+                    ? { requestedBy: ctx.user.id }
+                    : {}),
+            ...(input.deferRestart !== undefined ? { deferRestart: input.deferRestart } : {}),
+        }),
+        getVersions: async (input) => ps.getPackageVersions(input.name),
+        restartAddon: async (input) => ar.restartAddon(input.addonId),
+        retryLoad: async (input) => {
+            await ar.retryAddonLoad(input.packageName);
+            return { success: true };
+        },
+        getAutoUpdateSettings: async () => ps.getAutoUpdateSettings(),
+        setAutoUpdateSettings: async (input) => ps.setAutoUpdateSettings(input.channel, input.intervalSeconds),
+        getAddonAutoUpdate: async (input) => ps.getAddonAutoUpdate(input.addonId),
+        setAddonAutoUpdate: async (input) => ps.setAddonAutoUpdate(input.addonId, input.channel),
+        applyAutoUpdateToAll: async (input) => {
+            await ps.setAutoUpdateSettings(input.channel);
+            for (const pkg of ps.listInstalled()) {
+                await ps.setAddonAutoUpdate(pkg.name, input.channel);
+            }
+            return { success: true };
+        },
+        startBulkUpdate: async (input) => bulkCoordinator.start(input),
+        getBulkUpdateState: async ({ id }) => bulkCoordinator.get(id),
+        cancelBulkUpdate: async ({ id }) => bulkCoordinator.cancel(id),
+        listActiveBulkUpdates: async ({ nodeId }) => bulkCoordinator.list(nodeId),
+        custom: async (input) => {
+            const registry = ar.getCustomActionRegistry();
+            const entry = registry.resolve(input.addonId, input.action);
+            if (!entry) {
+                throw new server_1.TRPCError({
+                    code: 'NOT_FOUND',
+                    message: `addon '${input.addonId}' has no custom action '${input.action}'`,
+                });
+            }
+            ensureCustomActionAuth(ctx, entry.spec.auth);
+            const parsedInput = entry.spec.input.parse(input.input);
+            const result = await entry.handler(parsedInput);
+            return entry.spec.output.parse(result);
+        },
+        onAddonLogs: (input, push) => {
+            const unsubscribe = ls.subscribe({ tags: { addonId: input.addonId }, level: input.level }, (entry) => {
+                push({
+                    timestamp: entry.timestamp instanceof Date
+                        ? entry.timestamp.toISOString()
+                        : String(entry.timestamp),
+                    level: entry.level,
+                    message: entry.message,
+                    scope: entry.scope,
+                });
+            });
+            return unsubscribe ?? (() => { });
+        },
+    };
+}