@camstack/server 0.1.6 → 0.1.8

package/src/api/core/bulk-update-coordinator.ts

@@ -0,0 +1,302 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument -- The server installs @camstack/types@0.1.38 (last published) in server/backend/node_modules, while the workspace has 0.1.39 with the new BulkUpdate* types. ESLint's type-checker resolves against 0.1.38 and treats the new imports as `any`. Runtime is correct because Node module resolution walks up to root node_modules → workspace symlink. This disable mirrors the pattern in cap-providers.ts (same root cause). Will resolve when 0.1.39 is published and the local dist is synced. */
+import { randomUUID } from 'node:crypto'
+import {
+  EventCategory,
+  type BulkUpdateItem,
+  type BulkUpdateState,
+  type BulkUpdatePhase,
+  type BulkUpdateItemStatus,
+} from '@camstack/types'
+
+/**
+ * Narrow event-bus interface required by BulkUpdateCoordinator.
+ * Intentionally narrower than IEventBus: the coordinator only emits a single
+ * topic, so we avoid importing the full IEventBus (which lives in @camstack/types
+ * and would pull in all event-catalog types). The full IEventBus satisfies this
+ * interface structurally, so wiring in cap-providers.ts is cast-free.
+ */
+export interface IBulkUpdateEventBus {
+  emit(category: EventCategory.AddonsBulkUpdateProgress, payload: BulkUpdateState): void
+}
+
+export interface IBulkUpdateLogger {
+  info(message: string, ...args: unknown[]): void
+  warn(message: string, ...args: unknown[]): void
+  error(message: string, ...args: unknown[]): void
+  debug(message: string, ...args: unknown[]): void
+}
+
+export interface BulkUpdateCoordinatorDeps {
+  readonly eventBus: IBulkUpdateEventBus
+  readonly updateAddon: (input: { name: string; version: string }) => Promise<void>
+  readonly updateFrameworkPackage: (input: { packageName: string; version: string; deferRestart: boolean }) => Promise<void>
+  readonly restartServer: (input: { confirm: true }) => Promise<void>
+  readonly logger: IBulkUpdateLogger
+  /** Injectable clock for tests. Default: `() => Date.now()`. */
+  readonly clock?: () => number
+  /** How long to keep completed state before purging. Default: 5 minutes. */
+  readonly cleanupAfterMs?: number
+}
+
+export interface StartBulkUpdateInput {
+  readonly nodeId: string
+  readonly items: readonly { name: string; version: string; isSystem: boolean }[]
+}
+
+const DEFAULT_CLEANUP_AFTER_MS = 5 * 60 * 1_000
+
+export class BulkUpdateCoordinator {
+  private readonly states = new Map<string, BulkUpdateState>()
+  private readonly cancelFlags = new Map<string, { cancelled: boolean }>()
+  /**
+   * Tracks wall-clock time (ms) when each bulk completed. Used for lazy
+   * cleanup in `get()` — avoids scheduling a fake-timer `setTimeout` that
+   * would be eagerly fired by `vi.runAllTimersAsync()` in tests.
+   */
+  private readonly completedWallMs = new Map<string, number>()
+  /** Tracks which nodeIds currently have an active (non-completed) bulk update. */
+  private readonly activeNodeIds = new Set<string>()
+
+  private readonly now: () => number
+  private readonly cleanupAfterMs: number
+  /** Wall-clock source. Fake timers intercept `Date.now`, so tests can advance via `advanceTimersByTimeAsync`. */
+  private readonly wallNow: () => number
+
+  constructor(private readonly deps: BulkUpdateCoordinatorDeps) {
+    this.now = deps.clock ?? (() => Date.now())
+    this.cleanupAfterMs = deps.cleanupAfterMs ?? DEFAULT_CLEANUP_AFTER_MS
+    this.wallNow = () => Date.now()
+  }
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  start(input: StartBulkUpdateInput): { id: string } {
+    if (this.activeNodeIds.has(input.nodeId)) {
+      throw new Error(`Bulk update already in progress for node ${input.nodeId}`)
+    }
+
+    const id = randomUUID()
+
+    const items: BulkUpdateItem[] = input.items.map(i => ({
+      name: i.name,
+      isSystem: i.isSystem,
+      // fromVersion: the cap interface receives name+version+isSystem only;
+      // the caller (cap-providers.ts) may enrich this with the current version
+      // if available. Empty string is acceptable per plan spec.
+      fromVersion: '',
+      toVersion: i.version,
+      status: 'queued' as BulkUpdateItemStatus,
+    }))
+
+    const state: BulkUpdateState = {
+      id,
+      nodeId: input.nodeId,
+      startedAtMs: this.now(),
+      total: items.length,
+      completed: 0,
+      failed: 0,
+      current: null,
+      phase: 'regular',
+      cancelled: false,
+      items,
+    }
+
+    this.states.set(id, state)
+    this.activeNodeIds.add(input.nodeId)
+
+    const cancelFlag = { cancelled: false }
+    this.cancelFlags.set(id, cancelFlag)
+
+    // Emit initial state so clients see the bulk as started immediately
+    this.emit(state)
+
+    void this.runLoop(id, cancelFlag).catch(err => {
+      this.deps.logger.error('BulkUpdateCoordinator: loop crashed unexpectedly', err)
+    })
+
+    return { id }
+  }
+
+  get(id: string): BulkUpdateState | null {
+    const state = this.states.get(id)
+    if (state === undefined) return null
+    // Lazy cleanup: purge if the wall-clock elapsed since completion exceeds threshold.
+    // This avoids scheduling a long-lived setTimeout that would be eagerly fired
+    // by vi.runAllTimersAsync() in tests.
+    const completedWall = this.completedWallMs.get(id)
+    if (completedWall !== undefined && this.wallNow() - completedWall >= this.cleanupAfterMs) {
+      this.purge(id)
+      return null
+    }
+    return state
+  }
+
+  list(nodeId?: string): readonly BulkUpdateState[] {
+    const all = [...this.states.keys()]
+      .map(id => this.get(id))                // get() applies lazy-cleanup
+      .filter((s): s is BulkUpdateState => s !== null)
+    return nodeId === undefined ? all : all.filter(s => s.nodeId === nodeId)
+  }
+
+  cancel(id: string): { cancelled: boolean } {
+    const state = this.states.get(id)
+    const flag = this.cancelFlags.get(id)
+    if (state === undefined || flag === undefined) return { cancelled: false }
+    // Once restarting, the hub restart is committed — cancel has no effect.
+    if (state.phase === 'restarting') return { cancelled: false }
+    // Already completed.
+    if (state.completedAtMs !== undefined) return { cancelled: false }
+
+    flag.cancelled = true
+    this.mutate(id, s => ({ ...s, cancelled: true }))
+    return { cancelled: true }
+  }
+
+  // ── Internal loop ─────────────────────────────────────────────────
+
+  private async runLoop(id: string, cancelFlag: { cancelled: boolean }): Promise<void> {
+    const initial = this.states.get(id)!
+
+    // ── Phase 1: regular addons ──────────────────────────────────────
+    this.transitionPhase(id, 'regular')
+
+    for (const item of initial.items.filter(i => !i.isSystem)) {
+      if (cancelFlag.cancelled) break
+      await this.processItem(id, item, false)
+    }
+
+    // ── Phase 2: system packages (deferRestart: true) ────────────────
+    if (!cancelFlag.cancelled && initial.items.some(i => i.isSystem)) {
+      this.transitionPhase(id, 'system')
+
+      for (const item of initial.items.filter(i => i.isSystem)) {
+        if (cancelFlag.cancelled) break
+        await this.processItem(id, item, true)
+      }
+
+      // ── Phase 3: single restart ──────────────────────────────────
+      const anySystemPendingRestart = this.states.get(id)!.items.some(
+        i => i.isSystem && i.status === 'done-pending-restart',
+      )
+
+      if (anySystemPendingRestart && !cancelFlag.cancelled) {
+        this.transitionPhase(id, 'restarting')
+        try {
+          await this.deps.restartServer({ confirm: true })
+          // NOTE: In production, restartServer kills+respawns the hub process.
+          // Code below this point will not execute in that scenario.
+          // If the mock/stub returns (e.g. in tests), we fall through to finalizing.
+        } catch (err) {
+          // Restart failed but the npm installs already completed. Promote all
+          // done-pending-restart items to done with a caveat error so the UI
+          // can inform the user that a manual restart is needed.
+          this.deps.logger.error('BulkUpdateCoordinator: restart failed', err)
+          const errMsg = err instanceof Error ? err.message : String(err)
+          for (const it of this.states.get(id)!.items) {
+            if (it.status === 'done-pending-restart') {
+              this.setItemStatus(id, it.name, 'done', {
+                error: `Restart failed; manual restart required (${errMsg})`,
+              })
+            }
+          }
+        }
+      }
+    }
+
+    // ── Phase 4: finalize ────────────────────────────────────────────
+    // Reached when:
+    //  a) no system packages at all, OR
+    //  b) restart failed (process continued), OR
+    //  c) cancelled before the restart phase.
+    this.transitionPhase(id, 'finalizing')
+    this.completeBulk(id)
+  }
+
+  private async processItem(id: string, item: BulkUpdateItem, isSystem: boolean): Promise<void> {
+    this.setItemStatus(id, item.name, 'updating', { startedAtMs: this.now() })
+    this.mutate(id, s => ({ ...s, current: item.name }))
+    this.emit(this.states.get(id)!)
+
+    try {
+      if (isSystem) {
+        await this.deps.updateFrameworkPackage({
+          packageName: item.name,
+          version: item.toVersion,
+          deferRestart: true,
+        })
+        this.setItemStatus(id, item.name, 'done-pending-restart', { completedAtMs: this.now() })
+      } else {
+        await this.deps.updateAddon({ name: item.name, version: item.toVersion })
+        this.setItemStatus(id, item.name, 'done', { completedAtMs: this.now() })
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      this.setItemStatus(id, item.name, 'failed', { error: msg, completedAtMs: this.now() })
+    }
+
+    this.mutate(id, s => ({ ...s, current: null }))
+    this.emit(this.states.get(id)!)
+  }
+
+  // ── State mutation helpers ────────────────────────────────────────
+
+  private setItemStatus(
+    id: string,
+    name: string,
+    status: BulkUpdateItemStatus,
+    fields: { error?: string; startedAtMs?: number; completedAtMs?: number } = {},
+  ): void {
+    this.mutate(id, s => {
+      const items = s.items.map(it =>
+        it.name === name ? { ...it, status, ...fields } : it,
+      )
+      // completed = all terminal states: done | done-pending-restart | failed
+      const completed = items.filter(
+        it => it.status === 'done' || it.status === 'done-pending-restart' || it.status === 'failed',
+      ).length
+      const failed = items.filter(it => it.status === 'failed').length
+      return { ...s, items, completed, failed }
+    })
+  }
+
+  private transitionPhase(id: string, phase: BulkUpdatePhase): void {
+    this.mutate(id, s => ({ ...s, phase }))
+    this.emit(this.states.get(id)!)
+  }
+
+  private completeBulk(id: string): void {
+    this.mutate(id, s => ({ ...s, completedAtMs: this.now(), current: null }))
+    this.emit(this.states.get(id)!)
+
+    // Free the nodeId slot so a new bulk for the same node can be started
+    const nodeId = this.states.get(id)!.nodeId
+    this.activeNodeIds.delete(nodeId)
+
+    // Record wall-clock completion time for lazy cleanup in `get()`.
+    // We intentionally avoid scheduling a setTimeout here: a long-lived
+    // setTimeout (5 min) would be eagerly fired by vi.runAllTimersAsync()
+    // in tests, causing `get()` to return null immediately after the run.
+    // Instead, `get()` lazily checks whether the cleanup threshold has
+    // elapsed using Date.now() — which fake timers DO advance via
+    // advanceTimersByTimeAsync(), making the cleanup testable without
+    // a long-running timer.
+    this.completedWallMs.set(id, this.wallNow())
+  }
+
+  private purge(id: string): void {
+    this.states.delete(id)
+    this.cancelFlags.delete(id)
+    this.completedWallMs.delete(id)
+  }
+
+  /** Immutably update the state for the given id. No-op if id is unknown. */
+  private mutate(id: string, update: (s: BulkUpdateState) => BulkUpdateState): void {
+    const current = this.states.get(id)
+    if (current === undefined) return
+    this.states.set(id, update(current))
+  }
+
+  private emit(state: BulkUpdateState): void {
+    this.deps.eventBus.emit(EventCategory.AddonsBulkUpdateProgress, state)
+  }
+}

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

@@ -41,6 +41,7 @@ import type {
   Integration,
   IIntegrationRegistry,
   IDeviceProvider,
+  IBrokerProvider,
   CapabilityMethodAuth,
 } from '@camstack/types'
 import { asJsonObject, asJsonArray, errMsg } from '@camstack/types'
@@ -57,7 +58,10 @@ import type { AddonRegistryService } from '../../core/addon/addon-registry.servi
 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 { planDeleteTimeStamps } from '../../boot/integration-id-backfill'
 import { persistCollectionDisabled } from './collection-preference.js'
+import { BulkUpdateCoordinator } from './bulk-update-coordinator.js'
+import { FRAMEWORK_PACKAGE_ALLOWLIST } from '../../core/addon/addon-package.service.js'
 
 const execFileAsync = promisify(execFile)
 
@@ -114,6 +118,7 @@ export function buildNetworkQualityProvider(
         rttMs: input.rttMs,
         jitterMs: input.jitterMs,
         estimatedBandwidthKbps: input.estimatedBandwidthKbps,
+        packetLossPercent: input.packetLossPercent,
       })
     },
   }
@@ -477,9 +482,17 @@ export function buildNodesProvider(
       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 })
+      // 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) => {
@@ -515,10 +528,27 @@ function getDeviceProvider(ar: AddonRegistryService, addonId: string): IDevicePr
   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.
+ */
+export const INTEGRATION_CAP_MARKERS = new Set(['device-provider', 'device-adoption'])
+
 export function buildIntegrationsProvider(
   ar: AddonRegistryService,
   eb: EventBusService,
   loggingService: LoggingService,
+  capabilityRegistry: CapabilityRegistry | null,
 ): IIntegrationsProvider {
   const logger = loggingService.createLogger('integrations')
   const withProcessState = (i: Integration): IntegrationWithProcessState => ({
@@ -645,6 +675,77 @@ export function buildIntegrationsProvider(
         '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<{
+        removeByIntegration?: (input: { integrationId: string }) => Promise<{ removed: number }>
+        listAll?: (input: Record<string, never>) => Promise<readonly {
+          id: number; addonId: string; parentDeviceId: number | null; integrationId?: string
+        }[]>
+        setIntegrationId?: (input: { deviceId: number; integrationId: string }) => Promise<void>
+      }>('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 = 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: 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: 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({
@@ -694,11 +795,16 @@ export function buildIntegrationsProvider(
       // 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 =>
-          typeof c === 'string' ? c === 'device-provider' : c.name === 'device-provider',
-        ),
+        a.manifest.capabilities?.some(c => {
+          const name = typeof c === 'string' ? c : c.name
+          return typeof name === 'string' && INTEGRATION_CAP_MARKERS.has(name)
+        }),
       )
       const integrations = await reg.listIntegrations()
       return providerAddons.map(addon => {
@@ -710,6 +816,29 @@ export function buildIntegrationsProvider(
         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: 'device-adoption' | 'device-provider' =
+          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,
@@ -718,6 +847,9 @@ export function buildIntegrationsProvider(
           color,
           instanceMode,
           discoveryMode,
+          kind,
+          brokerKind,
+          supportsLocationImport,
           existingInstances: existing.map(i => ({
             id: i.id,
             name: i.name,
@@ -727,6 +859,33 @@ export function buildIntegrationsProvider(
       })
     },
     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<IBrokerProvider>('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: errMsg(err) }
+        }
+      }
+
+      // Default — RTSP/Frigate/ONVIF legacy path: probe the stream URL.
       const url = String(
         input.settings['main_stream_url'] ?? input.settings['url'] ?? '',
       ).trim()
@@ -806,8 +965,45 @@ export function buildAddonsProvider(
   moleculer: MoleculerService,
   configService: ConfigService,
   ctx: TrpcContext,
+  eb: EventBusService,
 ): IAddonsProvider {
   const broker = moleculer.broker as unknown as BrokerLike
+
+  // 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: Parameters<typeof eb.emit>[0]['category'], payload: unknown) => {
+      eb.emit({
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: { type: 'core', id: 'bulk-update-coordinator' },
+        category,
+        data: payload as Record<string, unknown>,
+      })
+    },
+  }
+
+  const bulkCoordinator = new 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<string>(FRAMEWORK_PACKAGE_ALLOWLIST)
+
   return {
     list: async () => {
       const rollbackable = ps.getRollbackablePackages()
@@ -843,9 +1039,10 @@ export function buildAddonsProvider(
     },
     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)
+      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
@@ -937,6 +1134,7 @@ export function buildAddonsProvider(
         : 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),
@@ -955,6 +1153,10 @@ export function buildAddonsProvider(
       }
       return { success: true as const }
     },
+    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)

package/src/api/core/capabilities.router.ts

@@ -28,12 +28,35 @@ export function createCapabilitiesRouter(
       }),
 
     setActiveSingleton: adminProcedure
-      .input(z.object({ capability: z.string(), addonId: z.string() }))
+      .input(z.object({
+        capability: z.string(),
+        addonId: z.string(),
+        nodeId: z.string().optional(),
+      }))
       .output(z.void())
       .mutation(async ({ input }) => {
         if (!registry) throw new Error('Capability registry unavailable')
-        await registry.setActiveSingleton(input.capability, input.addonId)
-        config.update('capabilities', { [input.capability]: input.addonId })
+        await registry.setActiveSingleton(input.capability, input.addonId, input.nodeId)
+        if (input.nodeId !== undefined) {
+          // Per-node override: persist under the node-qualified key so the boot
+          // restorer (`setNodeConfigReader`) replays it on restart.
+          config.set(`capabilities.singletonNode.${input.capability}.${input.nodeId}`, input.addonId)
+        } else {
+          // Cluster-global default: persist to the SAME key the boot restorer reads
+          // (addon-registry `setConfigReader` → `capabilities.singleton.<cap>`).
+          config.set(`capabilities.singleton.${input.capability}`, input.addonId)
+        }
+      }),
+
+    clearSingletonNodeOverride: adminProcedure
+      .input(z.object({ capability: z.string(), nodeId: z.string() }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.clearSingletonNodeOverride(input.capability, input.nodeId)
+        // Persist the cleared state as null so the boot restorer doesn't re-apply
+        // a stale override on restart.
+        config.set(`capabilities.singletonNode.${input.capability}.${input.nodeId}`, null)
       }),
 
     /**

package/src/api/core/logs.router.ts

@@ -18,6 +18,10 @@ const LogTagsSchema = z.object({
   nodeId: z.string().optional(),
   /** Numeric progressive id (or its string form for legacy callers). */
   deviceId: z.union([z.string(), z.number()]).optional(),
+  /** Parent container id — set on every accessory child's logs (and on the
+   *  container's own logs). Filtering by it returns the whole container subtree
+   *  (container + all children) in one query. */
+  containerDeviceId: z.union([z.string(), z.number()]).optional(),
   deviceName: z.string().optional(),
   integrationId: z.string().optional(),
   addonId: z.string().optional(),