@camstack/server 0.1.7 → 0.1.8

package/src/__tests__/cap-routers/device-link-overlay.spec.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests that `requireDeviceScoped` overlays `getStatus` results via
+ * `device-manager`'s `resolveLinkedStatus` when the device has linked
+ * properties for the requested cap.
+ *
+ * The overlay is transparent (null return = no-op) for the vast majority
+ * of reads; only devices with active links for the cap get the merged
+ * status back.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import { requireDeviceScoped } from '../../api/trpc/cap-mount-helpers.js'
+
+// ── Fake registry ────────────────────────────────────────────────────────────
+
+type ResolveLinkedStatus = (i: {
+  deviceId: number
+  cap: string
+  baseStatus: unknown
+}) => Promise<Record<string, unknown> | null>
+
+interface FakeDeviceManager {
+  resolveLinkedStatus: ResolveLinkedStatus
+}
+
+function makeRegistry(opts: {
+  nativeGetStatus: () => Promise<Record<string, unknown>>
+  nativeSetFanSpeed?: (i: unknown) => Promise<void>
+  resolveLinkedStatus: ResolveLinkedStatus
+}): CapabilityRegistry {
+  const nativeProvider = {
+    getStatus: opts.nativeGetStatus,
+    setFanSpeed: opts.nativeSetFanSpeed ?? vi.fn(async () => undefined),
+  }
+  const deviceManager: FakeDeviceManager = {
+    resolveLinkedStatus: opts.resolveLinkedStatus,
+  }
+  return {
+    getNativeProvider<T>(_capName: string, _deviceId: number): T | null {
+      return nativeProvider as unknown as T
+    },
+    getSingleton<T>(capability: string): T | null {
+      if (capability === 'device-manager') {
+        return deviceManager as unknown as T
+      }
+      return null
+    },
+    // Minimal no-op stubs for the rest of the CapabilityRegistry surface
+    // so TypeScript is satisfied without pulling in the real kernel class.
+    listCapabilities: vi.fn(() => []),
+    registerProvider: vi.fn(),
+    unregisterProvider: vi.fn(),
+    getCollection: vi.fn(() => []),
+    getCollectionEntries: vi.fn(() => []),
+    registerNativeProvider: vi.fn(),
+    unregisterNativeProvider: vi.fn(),
+    getProviderForDevice: vi.fn(() => null),
+    getBindings: vi.fn(() => ({ entries: [] })),
+    setActiveSingleton: vi.fn(),
+    getSingletonAddonId: vi.fn(() => null),
+    getAddonIdForProvider: vi.fn(() => null),
+    on: vi.fn(),
+    off: vi.fn(),
+    dispose: vi.fn(),
+  } as unknown as CapabilityRegistry
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+const DEVICE_ID = 668
+const CAP_NAME = 'vacuum-control' as Parameters<typeof requireDeviceScoped>[1]
+
+describe('requireDeviceScoped — getStatus overlay via resolveLinkedStatus', () => {
+  it('returns the overlaid status when resolveLinkedStatus returns a non-null object', async () => {
+    const base = { state: 'idle', battery: 80 }
+    const overlaid = { state: 'paused', cleanWater: { status: 'low', level: null } }
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      resolveLinkedStatus: vi.fn(async () => overlaid),
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    // Call via the Proxy — method is resolved lazily
+    const result = await (dispatcher as unknown as { getStatus: (i: { deviceId: number }) => Promise<unknown> })
+      .getStatus({ deviceId: DEVICE_ID })
+
+    expect(result).toEqual(overlaid)
+    expect(result).not.toEqual(base)
+  })
+
+  it('returns the base provider result unchanged when resolveLinkedStatus returns null (no links)', async () => {
+    const base = { state: 'cleaning', battery: 60 }
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      resolveLinkedStatus: vi.fn(async () => null),
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    const result = await (dispatcher as unknown as { getStatus: (i: { deviceId: number }) => Promise<unknown> })
+      .getStatus({ deviceId: DEVICE_ID })
+
+    expect(result).toEqual(base)
+  })
+
+  it('does NOT call resolveLinkedStatus for non-getStatus methods', async () => {
+    const base = { state: 'idle', battery: 90 }
+    const resolveLinkedStatus = vi.fn(async () => null)
+    const nativeSetFanSpeed = vi.fn(async () => undefined)
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      nativeSetFanSpeed,
+      resolveLinkedStatus,
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    await (dispatcher as unknown as { setFanSpeed: (i: { deviceId: number; speed: string }) => Promise<void> })
+      .setFanSpeed({ deviceId: DEVICE_ID, speed: 'high' })
+
+    expect(nativeSetFanSpeed).toHaveBeenCalledOnce()
+    // The overlay path must NOT be consulted for mutations
+    expect(resolveLinkedStatus).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/moleculer/uds-unowned-call.spec.ts

@@ -23,11 +23,16 @@ import { describe, it, expect, vi } from 'vitest'
 import {
   createParentUnownedCallHandler,
   CapRouteResolver,
+  CapRouteError,
+  HubNodeRegistry,
 } from '@camstack/kernel'
 import type {
   NodeCapAuthority,
   InProcessProviderLookup,
   CapRouteResolverDeps,
+  NodeNativeCapEntry,
+  HubLocalChildDispatcher,
+  CapCallInput,
 } from '@camstack/kernel'
 import type { ServiceBroker } from 'moleculer'
 
@@ -63,6 +68,42 @@ function hubBrokerFake(): ServiceBroker {
   return broker as unknown as ServiceBroker
 }
 
+/**
+ * Minimal `HubNodeRegistry`-shaped fake exposing only the lookup the unowned
+ * handler uses: `listNativeCapEntriesForDevice`. The handler depends solely on
+ * this method, so we don't need the full registry to exercise its routing.
+ */
+function nodeRegistryFake(
+  byDevice: Record<number, readonly NodeNativeCapEntry[]> = {},
+): HubNodeRegistry {
+  const fake = {
+    listNativeCapEntriesForDevice: (deviceId: number): readonly NodeNativeCapEntry[] =>
+      byDevice[deviceId] ?? [],
+  }
+  return fake as unknown as HubNodeRegistry
+}
+
+/**
+ * Hub-local UDS dispatcher fake (LocalChildRegistry surface). `resolveChildId`
+ * returns the configured childId on a (capName, deviceId) match else null;
+ * `callCapOnChild` records the call and echoes a sentinel result.
+ */
+function localDispatcherFake(owner?: { capName: string; deviceId: number; childId: string }): {
+  dispatcher: HubLocalChildDispatcher
+  resolveChildId: ReturnType<typeof vi.fn>
+  callCapOnChild: ReturnType<typeof vi.fn>
+} {
+  const resolveChildId = vi.fn((capName: string, deviceId?: number): string | null =>
+    owner !== undefined && capName === owner.capName && deviceId === owner.deviceId ? owner.childId : null,
+  )
+  const callCapOnChild = vi.fn(async (childId: string, input: CapCallInput) => ({
+    routedOverUds: childId,
+    capName: input.capName,
+  }))
+  const dispatcher: HubLocalChildDispatcher = { resolveChildId, callCapOnChild }
+  return { dispatcher, resolveChildId, callCapOnChild }
+}
+
 describe('hub onUnownedCall wiring (F0)', () => {
   it('resolver-first: resolves a hub-in-process cap through the real CapRouteResolver', async () => {
     const broker = hubBrokerFake()
@@ -83,7 +124,7 @@ describe('hub onUnownedCall wiring (F0)', () => {
     }
     const resolver = new CapRouteResolver(resolverDeps)
 
-    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker })
+    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker, nodeRegistry: nodeRegistryFake() })
 
     const result = await handler({ capName: 'settings-store', method: 'get', args: { key: 'k' } })
     expect(result).toEqual({ value: 'hub-resolved', params: { key: 'k' } })
@@ -104,7 +145,7 @@ describe('hub onUnownedCall wiring (F0)', () => {
       inProcessProviders: () => null,
     })
 
-    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker })
+    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker, nodeRegistry: nodeRegistryFake() })
 
     const result = await handler({ capName: 'system', method: 'info', args: undefined })
     expect(result).toEqual({ uptimeSec: 99, params: undefined })
@@ -115,9 +156,174 @@ describe('hub onUnownedCall wiring (F0)', () => {
     const broker = hubBrokerFake()
     // Mirrors the window before `this.resolver` is constructed: getResolver
     // returns null, so the handler goes straight to the broker fallback.
-    const handler = createParentUnownedCallHandler({ getResolver: () => null, broker })
+    const handler = createParentUnownedCallHandler({ getResolver: () => null, broker, nodeRegistry: nodeRegistryFake() })
+
+    const result = await handler({ capName: 'system', method: 'info', args: undefined })
+    expect(result).toEqual({ uptimeSec: 99, params: undefined })
+  })
+
+  it('deviceId-aware resolver: derives deviceId from args and routes via the resolver (no broker fallback)', async () => {
+    const broker = hubBrokerFake()
+
+    // A resolver-shaped fake that resolves a route ONLY when invoked with a
+    // deviceId — mirroring the real resolver routing a device-scoped native cap
+    // to its owning provider. Without a deviceId it returns no-provider.
+    let resolvedWithDeviceId: number | undefined
+    const resolver = {
+      resolveCapRoute: (capName: string, opts: { deviceId?: number }) => {
+        if (opts.deviceId === undefined) {
+          throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+        }
+        resolvedWithDeviceId = opts.deviceId
+        return { kind: 'hub-in-process', capName, deviceId: opts.deviceId }
+      },
+      dispatch: async () => ({ catalog: ['stream-a'] }),
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(),
+    })
+
+    // deviceId lives ONLY in args, NOT top-level — the handler must derive it.
+    const result = await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } })
+    expect(result).toEqual({ catalog: ['stream-a'] })
+    expect(resolvedWithDeviceId).toBe(7)
+    // Resolver served it via the derived deviceId — broker untouched.
+    expect(broker.call).not.toHaveBeenCalled()
+  })
+
+  it('pinned broker fallback: resolver finds nothing → call is pinned to the owning node', async () => {
+    const broker = hubBrokerFake()
+
+    // Resolver always returns no-provider for this device-scoped cap.
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+
+    const owner: NodeNativeCapEntry = { nodeId: 'agent', addonId: 'reolink', capName: 'stream-catalog', deviceId: 7 }
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(() => undefined)
+
+    // The broker call is pinned to the owning node via call-opts `{ nodeID }`.
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
+  })
+
+  it('back-compat: no resolvable device-owner → broker call stays UNPINNED (load-balanced)', async () => {
+    const broker = hubBrokerFake()
+
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(), // no owners for any device
+    })
 
     const result = await handler({ capName: 'system', method: 'info', args: undefined })
     expect(result).toEqual({ uptimeSec: 99, params: undefined })
+    // Unpinned: third arg (call-opts) is undefined — today's behavior preserved.
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toBeUndefined()
+  })
+
+  it('hub-local owner: device-native cap owned by a hub-local UDS child routes over UDS (broker untouched)', async () => {
+    const broker = hubBrokerFake()
+    // Resolver misses the device-scoped native cap (mirrors live behavior).
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => { throw new Error('dispatch should not be reached') },
+    }
+    const { dispatcher, resolveChildId, callCapOnChild } = localDispatcherFake({
+      capName: 'stream-catalog',
+      deviceId: 7,
+      childId: 'child-reolink',
+    })
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(), // empty — hub-local child is NOT in HubNodeRegistry
+      getLocalDispatcher: () => dispatcher,
+    })
+
+    const result = await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } })
+    expect(result).toEqual({ routedOverUds: 'child-reolink', capName: 'stream-catalog' })
+    expect(resolveChildId).toHaveBeenCalledWith('stream-catalog', 7)
+    expect(callCapOnChild).toHaveBeenCalledWith('child-reolink', {
+      capName: 'stream-catalog',
+      method: 'getCatalog',
+      args: { deviceId: 7 },
+      deviceId: 7,
+    })
+    expect(broker.call).not.toHaveBeenCalled()
+  })
+
+  it('remote owner: hub-local dispatcher misses → pinned broker call', async () => {
+    const broker = hubBrokerFake()
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => { throw new Error('dispatch should not be reached') },
+    }
+    const { dispatcher, callCapOnChild } = localDispatcherFake() // no local owner
+    const owner: NodeNativeCapEntry = { nodeId: 'agent', addonId: 'reolink', capName: 'stream-catalog', deviceId: 7 }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+      getLocalDispatcher: () => dispatcher,
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(() => undefined)
+
+    expect(callCapOnChild).not.toHaveBeenCalled()
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
+  })
+
+  it('no local dispatcher (getter returns null): behaves as before — HubNodeRegistry → broker', async () => {
+    const broker = hubBrokerFake()
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => { throw new Error('dispatch should not be reached') },
+    }
+    const owner: NodeNativeCapEntry = { nodeId: 'agent', addonId: 'reolink', capName: 'stream-catalog', deviceId: 7 }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+      getLocalDispatcher: () => null,
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(() => undefined)
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
   })
 })

package/src/api/core/__tests__/integration-markers.spec.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+import { INTEGRATION_CAP_MARKERS } from '../cap-providers.js'
+
+describe('integration cap markers', () => {
+  it('recognises device-adoption (not the old ha-discovery)', () => {
+    expect(INTEGRATION_CAP_MARKERS.has('device-adoption')).toBe(true)
+    expect(INTEGRATION_CAP_MARKERS.has('ha-discovery')).toBe(false)
+    expect(INTEGRATION_CAP_MARKERS.has('device-provider')).toBe(true)
+  })
+})

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,6 +58,7 @@ 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'
@@ -116,6 +118,7 @@ export function buildNetworkQualityProvider(
         rttMs: input.rttMs,
         jitterMs: input.jitterMs,
         estimatedBandwidthKbps: input.estimatedBandwidthKbps,
+        packetLossPercent: input.packetLossPercent,
       })
     },
   }
@@ -525,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 => ({
@@ -655,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({
@@ -704,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 => {
@@ -720,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,
@@ -728,6 +847,9 @@ export function buildIntegrationsProvider(
           color,
           instanceMode,
           discoveryMode,
+          kind,
+          brokerKind,
+          supportsLocationImport,
           existingInstances: existing.map(i => ({
             id: i.id,
             name: i.name,
@@ -737,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()

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(),

package/src/api/trpc/__tests__/client-ip.spec.ts

@@ -11,15 +11,17 @@
  */
 import { describe, it, expect } from 'vitest'
 import type { IncomingMessage } from 'node:http'
-import { extractClientIp, isRemoteClientIp } from '../client-ip.js'
+import { extractClientIp, extractUserAgent, isRemoteClientIp } from '../client-ip.js'
 
 function reqWith(opts: {
   xff?: string | string[]
   ip?: string
   remoteAddress?: string
+  userAgent?: string | string[]
 }): IncomingMessage {
   const headers: Record<string, string | string[]> = {}
   if (opts.xff !== undefined) headers['x-forwarded-for'] = opts.xff
+  if (opts.userAgent !== undefined) headers['user-agent'] = opts.userAgent
   const req = {
     headers,
     socket: { remoteAddress: opts.remoteAddress },
@@ -66,6 +68,30 @@ describe('extractClientIp', () => {
   })
 })
 
+describe('extractUserAgent', () => {
+  it('returns null for an absent request (mesh-originated call)', () => {
+    expect(extractUserAgent(undefined)).toBeNull()
+  })
+
+  it('returns null when the header is missing', () => {
+    expect(extractUserAgent(reqWith({}))).toBeNull()
+  })
+
+  it('reads the user-agent header', () => {
+    const req = reqWith({ userAgent: 'Mozilla/5.0 (Macintosh) Chrome/120' })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (Macintosh) Chrome/120')
+  })
+
+  it('reads the first entry when the header is an array', () => {
+    const req = reqWith({ userAgent: ['Mozilla/5.0 (X11) Firefox/121', 'ignored'] })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (X11) Firefox/121')
+  })
+
+  it('returns null for an empty header value', () => {
+    expect(extractUserAgent(reqWith({ userAgent: '' }))).toBeNull()
+  })
+})
+
 describe('isRemoteClientIp', () => {
   it('null → false (treated as LAN — safe default)', () => {
     expect(isRemoteClientIp(null)).toBe(false)