@camstack/server 0.1.3

package/src/api/core/cap-providers.ts

@@ -0,0 +1,993 @@
+/* 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`.
+ */
+import * as os from 'node:os'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { randomUUID } from 'node:crypto'
+import { TRPCError } from '@trpc/server'
+import type {
+  IAddonsProvider,
+  IIntegrationsProvider,
+  INetworkQualityProvider,
+  INodesProvider,
+  ISystemProvider,
+  IToastProvider,
+  IAnalysisDataPersistence,
+  Toast,
+  TopologyNode,
+  Integration,
+  IIntegrationRegistry,
+  IDeviceProvider,
+  CapabilityMethodAuth,
+} from '@camstack/types'
+import { asJsonObject, asJsonArray, errMsg } from '@camstack/types'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import { getCapUsageRegistry } from '@camstack/kernel'
+import type { ToastService, NotificationService } from '@camstack/core'
+import type { TrpcContext } from '../trpc/trpc.context.js'
+import type { FeatureService } from '../../core/feature/feature.service'
+import type { LoggingService } from '../../core/logging/logging.service'
+import type { EventBusService } from '../../core/events/event-bus.service'
+import type { AgentRegistryService } from '../../core/agent/agent-registry.service'
+import type { MoleculerService } from '../../core/moleculer/moleculer.service'
+import type { AddonRegistryService } from '../../core/addon/addon-registry.service'
+import type { AddonPackageService } from '../../core/addon/addon-package.service'
+import type { NetworkQualityService } from '../../core/network/network-quality.service'
+import type { ConfigService } from '../../core/config/config.service'
+import { persistCollectionDisabled } from './collection-preference.js'
+
+const execFileAsync = promisify(execFile)
+
+// ── system ──────────────────────────────────────────────────────────
+
+function getRetention(registry: CapabilityRegistry | null) {
+  return registry?.getSingleton<IAnalysisDataPersistence>('analysis-data-persistence')?.retention ?? null
+}
+
+export function buildSystemProvider(
+  feature: FeatureService,
+  registry: CapabilityRegistry | null,
+): ISystemProvider {
+  return {
+    info: async () => feature.getManifest(),
+    health: async () => ({ status: 'ok' as const, uptime: process.uptime() }),
+    featureFlags: async () => feature.getManifest(),
+    networkAddresses: async () => {
+      const ifaces = os.networkInterfaces()
+      const result: Array<{ name: string; address: string; family: string; internal: boolean }> = []
+      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 ─────────────────────────────────────────────────
+
+export function buildNetworkQualityProvider(
+  nq: NetworkQualityService,
+): INetworkQualityProvider {
+  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,
+      })
+    },
+  }
+}
+
+// ── 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.
+
+export function buildToastProvider(
+  toastService: ToastService | null,
+  ctx: TrpcContext,
+): IToastProvider {
+  return {
+    onToast: (_input, push) => {
+      if (!toastService) return () => {}
+      const userId = ctx.user?.id ?? 'anonymous'
+      const connectionId = randomUUID()
+      const unsubscribe = toastService.subscribe(connectionId, userId, (toast: Toast) => push(toast))
+      return unsubscribe ?? (() => {})
+    },
+  }
+}
+
+// ── nodes ───────────────────────────────────────────────────────────
+
+interface SubProcessLite {
+  readonly pid: number
+  readonly name: string
+  readonly state: string
+  readonly cpuPercent: number
+  readonly memoryRss: number
+  readonly uptimeSeconds: number
+  readonly addonIds?: readonly string[]
+  readonly groupId?: string | null
+}
+
+function getLocalIps(): string[] {
+  const interfaces = os.networkInterfaces()
+  const ips: string[] = []
+  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.
+ */
+export async function computeTopology(
+  agentRegistry: AgentRegistryService,
+  addonRegistry?: AddonRegistryService,
+): Promise<readonly TopologyNode[]> {
+  const nodes = await agentRegistry.listNodes()
+  const allAddons = addonRegistry?.listAddons() ?? []
+  const getInGroupAddonIds = (node: typeof nodes[number]): readonly string[] => {
+    const subs = (node.subProcesses ?? []) as readonly SubProcessLite[]
+    return subs.flatMap((p) => p.addonIds ?? [])
+  }
+  const addonCaps = new Map<string, readonly string[]>()
+  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<string, string>()
+  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: readonly string[] = (node as { agentAddons?: readonly string[] }).agentAddons ?? []
+    type NodeAddonEntry = { id: string; capabilities: readonly string[]; status: 'running' }
+    const allNodeAddons: NodeAddonEntry[] = node.isHub
+      ? allAddons.map((a) => {
+          const id = a.manifest?.id ?? 'unknown'
+          return { id, capabilities: [...(addonCaps.get(id) ?? [])], status: 'running' as const }
+        })
+      : agentAddonIds.map((addonId) => ({
+          id: addonId,
+          capabilities: [...(addonCaps.get(addonId) ?? [])],
+          status: 'running' as const,
+        }))
+    const inProcessAddons = allNodeAddons.filter((a) => !inGroupAddonIds.has(a.id))
+    const isolatedProcesses = ((node.subProcesses ?? []) as readonly SubProcessLite[])
+    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' as const,
+      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' as const,
+      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<string, {
+      category: string
+      total: number
+      healthy: number
+      addons: { id: string; status: string; cpuPercent: number; memoryRss: number }[]
+    }>()
+    const procByAddon = new Map<string, { cpuPercent: number; memoryRss: number; state: string }>()
+    for (const p of (node.subProcesses ?? []) as readonly SubProcessLite[]) {
+      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,
+    }
+  })
+}
+
+/**
+ * Local narrowing of Moleculer's broker. Going through `moleculer.broker`
+ * directly leaves typescript-eslint with `error`-typed access — Moleculer's
+ * `index.d.ts` chains through `eventemitter2` whose package.json has no
+ * `types` field; under `moduleResolution: node` the parser loses the chain
+ * even though `tsc --skipLibCheck` accepts it. Same shim is used in
+ * `addon-registry.service.ts`; consider hoisting if a third call site appears.
+ */
+interface BrokerLike {
+  call<T = unknown>(action: string, params?: unknown, opts?: { nodeID?: string; timeout?: number }): Promise<T>
+}
+
+export function buildNodesProvider(
+  agentRegistry: AgentRegistryService,
+  moleculer: MoleculerService,
+  addonRegistry?: AddonRegistryService,
+): INodesProvider {
+  const broker = moleculer.broker as unknown as BrokerLike
+  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: unknown = await addonRegistry.restartAddon(input.addonId)
+        if (typeof result === 'object' && result !== null && 'success' in result) {
+          return result as { success: boolean }
+        }
+        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 }) as { success: boolean; reason?: string }
+    },
+    restartNode: async (input) => {
+      return await broker.call('$process.restartAll', {}, {
+        nodeID: input.nodeId,
+        timeout: 60_000,
+      }) as { restarted: readonly string[]; failed: readonly string[] }
+    },
+    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<{
+          addons?: readonly { id: string; status: string; version?: string; packageName?: string }[]
+        }>('$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,
+            }) as { addons?: readonly { id: string; status: string; version?: string; packageName?: string }[] }
+            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: [] as readonly { id: string; status: string; version?: string; packageName?: string }[] }
+          }
+        }),
+      )
+
+      type NodeDeployment = { nodeId: string; name: string; version: string; status: string; synced: boolean }
+      const result: Record<string, { hubVersion: string; nodes: NodeDeployment[] }> = {}
+
+      for (const [addonId, hubAddon] of hubMap) {
+        const hubVersion = hubAddon.manifest.packageVersion
+        const addonNodes: NodeDeployment[] = [
+          { 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 = getCapUsageRegistry()
+      return reg.getGraph({ windowSeconds: input.windowSeconds, nowMs: Date.now() })
+    },
+    setProcessLogLevel: async (input) => {
+      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 },
+      )
+    },
+  }
+}
+
+// ── integrations ────────────────────────────────────────────────────
+
+interface IntegrationWithProcessState extends Integration {
+  readonly processState: string
+}
+
+function requireIntegrationRegistry(ar: AddonRegistryService): IIntegrationRegistry {
+  const reg = ar.getIntegrationRegistry()
+  if (!reg) throw new Error('IntegrationRegistry not available')
+  return reg
+}
+
+function isDeviceProvider(value: unknown): value is IDeviceProvider {
+  return value !== null
+    && typeof value === 'object'
+    && typeof Reflect.get(value, 'discoverDevices') === 'function'
+}
+
+function getDeviceProvider(ar: AddonRegistryService, addonId: string): IDeviceProvider | null {
+  const provider = ar.getCapabilityRegistry().getProviderByAddon('device-provider', addonId)
+  return isDeviceProvider(provider) ? provider : null
+}
+
+export function buildIntegrationsProvider(
+  ar: AddonRegistryService,
+  eb: EventBusService,
+  loggingService: LoggingService,
+): IIntegrationsProvider {
+  const logger = loggingService.createLogger('integrations')
+  const withProcessState = (i: Integration): IntegrationWithProcessState => ({
+    ...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 as Record<string, unknown>)[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 } },
+      )
+      await reg.deleteIntegration(input.id)
+
+      eb.emit({
+        id: `integration-deleted-${Date.now()}`,
+        timestamp: new Date(),
+        source: { type: 'integration', id: input.id },
+        category: 'integration.deleted',
+        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.
+      const providerAddons = addons.filter(a =>
+        a.process?.state !== 'failed' &&
+        a.manifest.capabilities?.some(c =>
+          typeof c === 'string' ? c === 'device-provider' : c.name === 'device-provider',
+        ),
+      )
+      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'
+        return {
+          addonId: m.id,
+          name: m.name ?? m.id,
+          description: m.description ?? '',
+          iconUrl: icon ? `/api/addon-assets/${m.id}/${icon}` : null,
+          color,
+          instanceMode,
+          discoveryMode,
+          existingInstances: existing.map(i => ({
+            id: i.id,
+            name: i.name,
+          })),
+          canAdd: instanceMode === 'multiple' || existing.length === 0,
+        }
+      })
+    },
+    testConnection: async (input) => {
+      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 = asJsonObject(JSON.parse(stdout))
+        const streams = 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: ${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: TrpcContext, level: CapabilityMethodAuth): void {
+  if (level === 'public') return
+  if (!ctx.user) {
+    throw new TRPCError({ code: 'UNAUTHORIZED' })
+  }
+  if (level === 'protected') return
+  if (level === 'admin') {
+    if (!ctx.user.isAdmin) {
+      throw new 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: string): boolean {
+  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: BrokerLike,
+  nodeId: string,
+): Promise<readonly { name: string; version: string }[]> {
+  const status = await broker.call<{
+    addons?: readonly { id: string; status: string; version?: string; packageName?: string }[]
+  }>('$agent.status', {}, { nodeID: nodeId, timeout: 5_000 })
+  const out: { name: string; version: string }[] = []
+  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
+}
+
+export function buildAddonsProvider(
+  ar: AddonRegistryService,
+  ps: AddonPackageService,
+  ls: LoggingService,
+  moleculer: MoleculerService,
+  configService: ConfigService,
+  ctx: TrpcContext,
+): IAddonsProvider {
+  const broker = moleculer.broker as unknown as BrokerLike
+  return {
+    list: async () => {
+      const rollbackable = ps.getRollbackablePackages()
+      const healthByPackage = new Map<string, ReturnType<typeof ar.getAddonHealthSnapshot>[number]>()
+      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
+      if (nodeId === undefined || isHubNode(nodeId)) return ps.checkUpdates()
+      const installed = await fetchAgentInstalledPackages(broker, nodeId)
+      return ps.checkUpdatesForInstalled(installed)
+    },
+    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 import('../../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' as const : 'singleton' as const
+      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 TRPCError({
+          code: 'NOT_FOUND',
+          message: `Unknown capability: ${input.capName}`,
+        })
+      }
+      if (found.mode !== 'collection') {
+        throw new TRPCError({
+          code: 'BAD_REQUEST',
+          message: `Capability "${input.capName}" is not a collection`,
+        })
+      }
+      if (!found.providers.includes(input.addonId)) {
+        throw new 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)
+      persistCollectionDisabled(
+        configService,
+        input.capName,
+        updated?.disabledProviders ?? [],
+      )
+      return { success: true as const }
+    },
+    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 }
+          : {}),
+    }),
+    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 as const }
+    },
+    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 as const }
+    },
+    custom: async (input) => {
+      const registry = ar.getCustomActionRegistry()
+      const entry = registry.resolve(input.addonId, input.action)
+      if (!entry) {
+        throw new 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: { timestamp: Date | string | number; level: string; message: string; scope?: string }) => {
+          push({
+            timestamp: entry.timestamp instanceof Date
+              ? entry.timestamp.toISOString()
+              : String(entry.timestamp),
+            level: entry.level,
+            message: entry.message,
+            scope: entry.scope,
+          })
+        },
+      )
+      return unsubscribe ?? (() => {})
+    },
+  }
+}
+
+// Avoid an unused-import warning in environments where NotificationService
+// is referenced solely via type imports above.
+export type _NotificationServiceHint = NotificationService