@camstack/server 0.1.6 → 0.1.8

package/src/api/trpc/trpc.middleware.ts

@@ -3,8 +3,12 @@ import superjson from 'superjson'
 import { METHOD_ACCESS_MAP } from '@camstack/types'
 import type { TrpcContext } from './trpc.context'
 import { checkScopeAccess } from './scope-access.js'
+import { formatTrpcError } from './cap-route-error-formatter.js'
 
-const t = initTRPC.context<TrpcContext>().create({ transformer: superjson })
+const t = initTRPC.context<TrpcContext>().create({
+  transformer: superjson,
+  errorFormatter: formatTrpcError,
+})
 
 // ---------------------------------------------------------------------------
 // Async-generator subscription helpers (tRPC v11 — replaces deprecated observable)

package/src/api/trpc/trpc.router.ts

@@ -11,7 +11,7 @@ import { trpcRouter } from './trpc.middleware'
 //   streaming → `streamingManagement` cap, events → `eventQuery` cap,
 //   logs → kept manual, live → kept manual, processes → `processMgmt`
 //   cap, agents → `nodes` cap, sessions → `session` cap, trackMedia /
-//   trackTrail → caps, recording → `recordingEngine` cap, network →
+//   trackTrail → caps, network →
 //   `networkQuality` cap, addons → `addons` cap, bridgePipeline removed
 //   (legacy), detection → `detectionConfig` cap, capabilities → kept
 //   manual, update → addons cap, addonPages → cap, notification →
@@ -20,7 +20,7 @@ import { trpcRouter } from './trpc.middleware'
 //   `pipelineExecutor` cap, pipeline → `pipelineConfig` cap,
 //   systemEvents → kept manual.
 import type { CapabilityRegistry } from '@camstack/kernel'
-import type { InferProvider } from '@camstack/types'
+import type { InferProvider, BrokerConsumerAttribution } from '@camstack/types'
 import {
   pipelineExecutorCapability,
   pipelineRunnerCapability,
@@ -30,6 +30,7 @@ import {
   platformProbeCapability,
   decoderCapability,
   localNetworkCapability,
+  webrtcSessionCapability,
 } from '@camstack/types'
 import {
   // The auto-mount covers ~75 caps. The handful re-imported below back
@@ -51,6 +52,7 @@ import {
   createCapRouter_integrations,
   createCapRouter_nodes,
   createCapRouter_addons,
+  createCapRouter_webrtcSession,
 } from './generated-cap-routers'
 import { mountAllCaps } from './generated-cap-mounts.js'
 import {
@@ -74,6 +76,8 @@ import { createCapabilitiesRouter } from '../core/capabilities.router.js'
 import { createStreamProbeRouter } from '../core/stream-probe.router.js'
 import { createHwAccelRouter } from '../core/hwaccel.router.js'
 import { requireSingleton, firstSupported, anySupports } from './cap-mount-helpers.js'
+import { extractUserAgent } from './client-ip.js'
+import type { TrpcContext } from './trpc.context.js'
 import type { AuthService } from '../../core/auth/auth.service'
 import type { ConfigService } from '../../core/config/config.service'
 import type { FeatureService } from '../../core/feature/feature.service'
@@ -108,6 +112,63 @@ export interface RouterServices {
   streamProbe: StreamProbeService | null
 }
 
+type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
+type CreateSessionInput = Parameters<WebrtcSessionProvider['createSession']>[0]
+type HandleOfferInput = Parameters<WebrtcSessionProvider['handleOffer']>[0]
+
+/**
+ * Merge the server-read User-Agent into a signaling call's
+ * `consumerAttribution`, building a NEW input object (immutable — never
+ * mutates the caller's input). When `userAgent` is null (mesh-originated
+ * call, or a client that omits the header) the input passes through
+ * unchanged. Any client-supplied `userAgent` is OVERWRITTEN — the hub
+ * trusts only the request context, never the client.
+ */
+export function enrichInputWithUserAgent<TInput extends { consumerAttribution?: BrokerConsumerAttribution }>(
+  input: TInput,
+  userAgent: string | null,
+): TInput {
+  if (userAgent === null) return input
+  const base: BrokerConsumerAttribution = input.consumerAttribution ?? { kind: 'webrtc-browser' }
+  return {
+    ...input,
+    consumerAttribution: { ...base, userAgent },
+  }
+}
+
+/**
+ * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
+ *
+ * It was meant to give CGNAT/4G viewers a clean relay↔relay path, but werift's
+ * TURN media-forward is unreliable between two real TURN servers (relay↔relay
+ * connects yet media never arrives → connected-but-black), and forcing relay
+ * ALSO kills the direct LAN/Tailscale host pair — which carries full native
+ * quality with no relay. We now offer ALL candidates (host incl. the hub's
+ * advertised Tailscale address, srflx, relay) and let ICE nominate the best
+ * reachable pair: direct when possible, relay only as a fallback. The
+ * `relayOnly` cap field + broker support remain for when relay media-forward
+ * is fixed.
+ *
+ * The wrapper additionally enriches the `createSession` / `handleOffer`
+ * subscriber attribution with the originating client's User-Agent, read
+ * from the tRPC request context (browser sessions). All OTHER methods
+ * delegate straight through — auth, the remote-proxy factory and every
+ * signaling behaviour are untouched.
+ */
+export function wrapWebrtcSessionProviderWithRelay(
+  provider: WebrtcSessionProvider,
+  ctx: TrpcContext,
+): WebrtcSessionProvider {
+  const userAgent = extractUserAgent(ctx.req)
+  return {
+    ...provider,
+    createSession: (input: CreateSessionInput) =>
+      provider.createSession(enrichInputWithUserAgent(input, userAgent)),
+    handleOffer: (input: HandleOfferInput) =>
+      provider.handleOffer(enrichInputWithUserAgent(input, userAgent)),
+  }
+}
+
 /**
  * Build the AppRouter. Mounts every codegen'd cap router via the auto-
  * mount entrypoint and overrides the handful that need service-backed
@@ -166,7 +227,7 @@ function buildCapabilityRouters(services: RouterServices) {
       (ctx) => buildToastProvider(services.toastService, ctx),
     ),
     integrations: createCapRouter_integrations(
-      (_ctx) => buildIntegrationsProvider(services.addonRegistry, services.eventBus, services.loggingService),
+      (_ctx) => buildIntegrationsProvider(services.addonRegistry, services.eventBus, services.loggingService, services.capabilityRegistry),
     ),
     nodes: createCapRouter_nodes(
       (_ctx) => buildNodesProvider(
@@ -183,6 +244,7 @@ function buildCapabilityRouters(services: RouterServices) {
         services.moleculer,
         services.configService,
         ctx,
+        services.eventBus,
       ),
     ),
 
@@ -253,6 +315,25 @@ function buildCapabilityRouters(services: RouterServices) {
       },
     ),
 
+    // ── Cap override: server-detected remote → relay-only ────────────
+    // The broker (a forked addon) can't see the HTTP request, so it
+    // can't tell a LAN viewer from a remote one. We override only the
+    // `getProvider` accessor to return a per-request provider whose
+    // `createSession` carries a server-computed `relayOnly` flag derived
+    // from the client IP in `ctx.req`. Remote (CGNAT/4G) viewers force
+    // TURN-relay-only ICE; LAN viewers keep the direct host/srflx path.
+    // All other methods delegate straight through, and the cross-node
+    // remote-proxy routing is preserved (forked/agent-hosted brokers).
+    webrtcSession: createCapRouter_webrtcSession(
+      (ctx) => {
+        const provider = services.capabilityRegistry
+          ?.getSingleton<WebrtcSessionProvider>('webrtc-session') ?? null
+        return provider ? wrapWebrtcSessionProviderWithRelay(provider, ctx) : null
+      },
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as WebrtcSessionProvider | null,
+    ),
+
     // NOT MOUNTED — legacy provider shapes (positional args / sync
     // returns) that don't match the codegen routers' {input}-object +
     // Promise<T> contract. Tracked by `LEGACY_SHAPE_SKIP` in

package/src/boot/__tests__/integration-id-backfill.spec.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest'
+import { planIntegrationIdBackfill, planDeleteTimeStamps, runIntegrationIdBackfill } from '../integration-id-backfill'
+
+describe('planDeleteTimeStamps', () => {
+  it('claims an untagged top-level device of the deleted integration\'s single-integration addon', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [{ id: 'int_rtsp', addonId: 'provider-rtsp' }],
+      [
+        { id: 4, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 6, addonId: 'provider-rtsp', parentDeviceId: null },
+      ],
+    )
+    expect(stamps).toEqual([
+      { deviceId: 4, integrationId: 'int_rtsp' },
+      { deviceId: 6, integrationId: 'int_rtsp' },
+    ])
+  })
+
+  it('returns no stamps for a multi-integration addon (ambiguous — never auto-claim)', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_a',
+      [{ id: 'int_a', addonId: 'provider-ha' }, { id: 'int_b', addonId: 'provider-ha' }],
+      [{ id: 11, addonId: 'provider-ha', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('only returns stamps for the integration being deleted, not siblings of other addons', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [{ id: 'int_rtsp', addonId: 'provider-rtsp' }, { id: 'int_onvif', addonId: 'provider-onvif' }],
+      [
+        { id: 4, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 5, addonId: 'provider-onvif', parentDeviceId: null },
+      ],
+    )
+    expect(stamps).toEqual([{ deviceId: 4, integrationId: 'int_rtsp' }])
+  })
+
+  it('skips devices already tagged with the deleted integration', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [{ id: 'int_rtsp', addonId: 'provider-rtsp' }],
+      [{ id: 4, addonId: 'provider-rtsp', parentDeviceId: null, integrationId: 'int_rtsp' }],
+    )
+    expect(stamps).toEqual([])
+  })
+})
+
+describe('planIntegrationIdBackfill', () => {
+  it('stamps a top-level untagged device whose addon has exactly one integration', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [{ id: 10, addonId: 'provider-rtsp', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([{ deviceId: 10, integrationId: 'int_1' }])
+  })
+
+  it('skips devices whose addon hosts multiple integrations (ambiguous)', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_a', addonId: 'provider-ha' }, { id: 'int_b', addonId: 'provider-ha' }],
+      [{ id: 11, addonId: 'provider-ha', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('skips already-tagged devices and child devices', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [
+        { id: 12, addonId: 'provider-rtsp', parentDeviceId: null, integrationId: 'int_1' },
+        { id: 13, addonId: 'provider-rtsp', parentDeviceId: 12 },
+      ],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('skips devices whose addon has no integration', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [{ id: 14, addonId: 'provider-onvif', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+})
+
+describe('runIntegrationIdBackfill', () => {
+  it('applies stamps and reports the count, skipping failures', async () => {
+    const stamped: Array<{ deviceId: number; integrationId: string }> = []
+    const result = await runIntegrationIdBackfill({
+      listIntegrations: async () => [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      listDevices: async () => [
+        { id: 10, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 11, addonId: 'provider-rtsp', parentDeviceId: null },
+      ],
+      setIntegrationId: async (deviceId, integrationId) => {
+        if (deviceId === 11) throw new Error('boom')
+        stamped.push({ deviceId, integrationId })
+      },
+      logger: { info: () => {}, warn: () => {} },
+    })
+    expect(result).toEqual({ stamped: 1 })
+    expect(stamped).toEqual([{ deviceId: 10, integrationId: 'int_1' }])
+  })
+
+  it('does nothing when there is nothing to stamp', async () => {
+    const result = await runIntegrationIdBackfill({
+      listIntegrations: async () => [],
+      listDevices: async () => [],
+      setIntegrationId: async () => { throw new Error('should not be called') },
+      logger: { info: () => {}, warn: () => {} },
+    })
+    expect(result).toEqual({ stamped: 0 })
+  })
+})

package/src/boot/integration-id-backfill.ts

@@ -0,0 +1,109 @@
+/**
+ * One-time integration-id backfill for devices created before the
+ * device-manager forwarder started stamping `integrationId` (camera
+ * providers). Maps each addon that hosts EXACTLY ONE integration to that
+ * integration id, then stamps top-level untagged devices of those addons.
+ * Multi-instance addons (e.g. Home Assistant with several brokers) are
+ * ambiguous on `addonId` alone and are skipped — they stamp going forward.
+ */
+
+export interface BackfillIntegration {
+  readonly id: string
+  readonly addonId: string
+}
+
+export interface BackfillDevice {
+  readonly id: number
+  readonly addonId: string
+  readonly parentDeviceId: number | null
+  readonly integrationId?: string
+}
+
+export interface BackfillStamp {
+  readonly deviceId: number
+  readonly integrationId: string
+}
+
+export function planIntegrationIdBackfill(
+  integrations: readonly BackfillIntegration[],
+  devices: readonly BackfillDevice[],
+): readonly BackfillStamp[] {
+  const singleByAddon = new Map<string, string>()
+  const ambiguous = new Set<string>()
+  for (const integration of integrations) {
+    if (ambiguous.has(integration.addonId)) continue
+    if (singleByAddon.has(integration.addonId)) {
+      singleByAddon.delete(integration.addonId)
+      ambiguous.add(integration.addonId)
+      continue
+    }
+    singleByAddon.set(integration.addonId, integration.id)
+  }
+
+  const stamps: BackfillStamp[] = []
+  for (const device of devices) {
+    if (device.parentDeviceId !== null) continue
+    if (device.integrationId !== undefined && device.integrationId !== '') continue
+    const integrationId = singleByAddon.get(device.addonId)
+    if (integrationId === undefined) continue
+    stamps.push({ deviceId: device.id, integrationId })
+  }
+  return stamps
+}
+
+/**
+ * Stamps to apply at integration-DELETE time so a cascade removes legacy
+ * un-tagged devices too. The boot backfill only runs on startup; a device
+ * created before stamping (or whose provider never stamps, e.g. `provider-rtsp`)
+ * keeps no `integrationId`, so once its integration is deleted it would orphan
+ * forever — `removeByIntegration` matches on `integrationId` and finds nothing.
+ *
+ * Run this in the delete handler BEFORE deleting the integration record (while
+ * it is still present in `integrations`), then stamp the returned devices and
+ * let `removeByIntegration` cascade them. Reuses the boot backfill's safety
+ * rule (only addons hosting exactly ONE integration are unambiguous) and
+ * filters to the integration being deleted so siblings are never touched.
+ */
+export function planDeleteTimeStamps(
+  integrationId: string,
+  integrations: readonly BackfillIntegration[],
+  devices: readonly BackfillDevice[],
+): readonly BackfillStamp[] {
+  return planIntegrationIdBackfill(integrations, devices).filter(
+    (stamp) => stamp.integrationId === integrationId,
+  )
+}
+
+export interface BackfillLogger {
+  readonly info: (message: string, meta?: Record<string, unknown>) => void
+  readonly warn: (message: string, meta?: Record<string, unknown>) => void
+}
+
+export interface IntegrationIdBackfillDeps {
+  readonly listIntegrations: () => Promise<readonly BackfillIntegration[]>
+  readonly listDevices: () => Promise<readonly BackfillDevice[]>
+  readonly setIntegrationId: (deviceId: number, integrationId: string) => Promise<void>
+  readonly logger: BackfillLogger
+}
+
+export async function runIntegrationIdBackfill(
+  deps: IntegrationIdBackfillDeps,
+): Promise<{ stamped: number }> {
+  const [integrations, devices] = await Promise.all([deps.listIntegrations(), deps.listDevices()])
+  const stamps = planIntegrationIdBackfill(integrations, devices)
+  let stamped = 0
+  for (const stamp of stamps) {
+    try {
+      await deps.setIntegrationId(stamp.deviceId, stamp.integrationId)
+      stamped++
+    } catch (err) {
+      deps.logger.warn('integrationId backfill: stamp failed', {
+        deviceId: stamp.deviceId,
+        integrationId: stamp.integrationId,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+  if (stamped > 0) deps.logger.info('integrationId backfill complete', { stamped })
+  return { stamped }
+}

package/src/core/addon/__tests__/addon-row-manifest.spec.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+
+import { overlayDeclaration } from '../addon-row-manifest.js'
+
+/**
+ * Regression: after the HA broker rework, redeploying provider-homeassistant
+ * (broker + device-adoption) left the integration picker without Home
+ * Assistant. `loadNewAddons` refreshed `entry.declaration` to the new caps but
+ * `listAddons` built its row manifest from the STALE `entry.addon.manifest`
+ * (still [broker, ha-discovery]), so `getAvailableTypes` filtered HA out.
+ */
+interface TestManifest {
+  id: string
+  name: string
+  icon?: string
+  brokerKind?: string
+  capabilities?: ReadonlyArray<{ name: string }>
+}
+
+describe('overlayDeclaration — listAddons row manifest freshness', () => {
+  const base = { id: 'provider-homeassistant', name: 'Home Assistant' }
+
+  it('prefers the fresh declaration capabilities over the stale instance manifest', () => {
+    const instanceManifest: TestManifest = {
+      ...base,
+      capabilities: [{ name: 'broker' }, { name: 'ha-discovery' }],
+    }
+    const declaration: Partial<TestManifest> = {
+      capabilities: [{ name: 'broker' }, { name: 'device-adoption' }],
+      brokerKind: 'home-assistant',
+    }
+
+    const merged = overlayDeclaration(instanceManifest, declaration)
+
+    expect(merged.capabilities).toEqual([{ name: 'broker' }, { name: 'device-adoption' }])
+    expect(merged.brokerKind).toBe('home-assistant')
+  })
+
+  it('keeps the instance manifest when no fresh declaration exists', () => {
+    const instanceManifest: TestManifest = { ...base, capabilities: [{ name: 'broker' }] }
+
+    const merged = overlayDeclaration(instanceManifest, undefined)
+
+    expect(merged.capabilities).toEqual([{ name: 'broker' }])
+  })
+
+  it('fills gaps from the instance manifest for keys the declaration omits', () => {
+    const instanceManifest: TestManifest = {
+      ...base,
+      icon: 'assets/icon.svg',
+      capabilities: [{ name: 'broker' }],
+    }
+    const declaration: Partial<TestManifest> = {
+      capabilities: [{ name: 'broker' }, { name: 'device-adoption' }],
+    }
+
+    const merged = overlayDeclaration(instanceManifest, declaration)
+
+    expect(merged.icon).toBe('assets/icon.svg')
+    expect(merged.capabilities).toContainEqual({ name: 'device-adoption' })
+  })
+})

package/src/core/addon/addon-call-gateway.ts

@@ -0,0 +1,157 @@
+/**
+ * `AddonCallGateway` — the SINGLE hub-side router for addon-LEVEL calls (the
+ * surfaces the removed per-addon Moleculer broker used to carry: routes,
+ * custom-actions, settings — see `AddonCallTarget`).
+ *
+ * Why this exists: that routing decision (is the addon running in-process on
+ * the hub, as a forked hub-local CHILD reachable over UDS, or on a REMOTE
+ * agent over Moleculer?) used to be duplicated per surface — routes/custom in
+ * `addon-registry.service.ts`, settings in `addon-settings-provider.ts`. When
+ * the UDS migration ported routes+custom to `callAddonOnChild`, settings was
+ * left on the dead `<addonId>.settings.<method>` Moleculer path because nothing
+ * centralised "dispatch an addon-level call to wherever the addon runs". Every
+ * forked hub-local addon's settings panel silently went empty for months.
+ *
+ * Now every addon-level surface routes through `callForked` here. Combined with
+ * the exhaustive `AddonCallTarget` union (a `never`-checked dispatch in
+ * `createChildAddonCallDispatch`), a future surface can't be half-wired without
+ * a compile error — the class of "missed link" is closed.
+ */
+import type { AddonCallInput, LocalChildRegistry } from '@camstack/kernel'
+
+/** An addon-level call minus its `addonId` — the gateway merges that in. */
+export type AddonCallSurface = Omit<AddonCallInput, 'addonId'>
+
+/**
+ * Minimal structural view of the Moleculer broker (remote-agent leg) — typed
+ * locally because the lint type-checker can't resolve Moleculer's
+ * `ServiceBroker` (mirrors the pattern in `addon-settings-provider.ts`).
+ */
+export interface AddonCallBroker {
+  readonly registry: unknown
+  call(
+    action: string,
+    params: Record<string, unknown>,
+    opts?: { readonly nodeID?: string; readonly timeout?: number },
+  ): Promise<unknown>
+}
+
+/** Where an addon physically runs — the routing decision, made in one place. */
+export type AddonCallDestination =
+  | { readonly kind: 'in-process' }
+  | { readonly kind: 'hub-local-child' }
+  | { readonly kind: 'remote-agent'; readonly baseNodeId: string }
+
+export interface AddonCallGatewayDeps {
+  /** This hub's node id (for the local short-circuit). */
+  readonly hubNodeId: string
+  /** Which node hosts a given addon ('hub' / hubNodeId = on this hub). */
+  readonly resolveNode: (addonId: string) => string
+  /** UDS registry of forked hub-local children (null before it's wired). */
+  readonly getChildRegistry: () => LocalChildRegistry | null
+  /** Moleculer broker for the remote-agent leg. */
+  readonly broker: AddonCallBroker
+}
+
+const REMOTE_TIMEOUT_MS = 10_000
+
+export class AddonCallGateway {
+  constructor(private readonly deps: AddonCallGatewayDeps) {}
+
+  /**
+   * Classify where an addon runs. `nodeId: 'hub'` from a caller means "the hub
+   * cluster", NOT "force in-process" — a forked hub-local addon is still a
+   * `hub-local-child` (UDS), never the in-process path (which is only the
+   * `@camstack/core` builtins that have no forked runner).
+   */
+  classify(addonId: string, explicitNodeId?: string): AddonCallDestination {
+    const resolved = this.deps.resolveNode(addonId)
+    const onHub = resolved === 'hub' || resolved === this.deps.hubNodeId
+    if (onHub) {
+      const childRegistry = this.deps.getChildRegistry()
+      if (childRegistry !== null && childRegistry.isChildKnown(addonId)) {
+        return { kind: 'hub-local-child' }
+      }
+      return { kind: 'in-process' }
+    }
+    const onThisHub = explicitNodeId === 'hub' || explicitNodeId === this.deps.hubNodeId
+    const baseNodeId = explicitNodeId && !onThisHub ? explicitNodeId : resolved
+    return { kind: 'remote-agent', baseNodeId }
+  }
+
+  /** True when the addon is an in-process hub builtin (caller invokes directly). */
+  isInProcess(addonId: string, explicitNodeId?: string): boolean {
+    return this.classify(addonId, explicitNodeId).kind === 'in-process'
+  }
+
+  /**
+   * Dispatch a forked addon-level call to wherever the addon runs:
+   *   - `hub-local-child` → UDS `LocalChildRegistry.callAddonOnChild`
+   *   - `remote-agent`    → Moleculer `broker.call`
+   * Throws for `in-process` — that addon has no forked surface, so the caller
+   * must invoke the in-process instance directly (the invocation is
+   * surface-specific; only the ROUTING is centralised here).
+   */
+  async callForked(addonId: string, input: AddonCallSurface, explicitNodeId?: string): Promise<unknown> {
+    const dest = this.classify(addonId, explicitNodeId)
+    const fullInput: AddonCallInput = { ...input, addonId }
+    switch (dest.kind) {
+      case 'hub-local-child': {
+        const childRegistry = this.deps.getChildRegistry()
+        if (childRegistry === null) {
+          throw new Error(`AddonCallGateway: child registry unavailable for "${addonId}"`)
+        }
+        return childRegistry.callAddonOnChild(addonId, fullInput)
+      }
+      case 'remote-agent':
+        return this.callRemoteAgent(addonId, dest.baseNodeId, fullInput)
+      case 'in-process':
+        throw new Error(`AddonCallGateway: addon "${addonId}" runs in-process — invoke it directly`)
+      default: {
+        const _exhaustive: never = dest
+        throw new Error(`AddonCallGateway: unhandled destination ${JSON.stringify(_exhaustive)}`)
+      }
+    }
+  }
+
+  /** Map an addon-level call to the remote agent's Moleculer action. */
+  private async callRemoteAgent(addonId: string, baseNodeId: string, input: AddonCallInput): Promise<unknown> {
+    const workerNodeId = this.resolveWorkerNodeId(addonId, baseNodeId)
+    const opts = workerNodeId
+      ? { nodeID: workerNodeId, timeout: REMOTE_TIMEOUT_MS }
+      : { timeout: REMOTE_TIMEOUT_MS }
+    if (input.target === 'settings') {
+      if (input.method == null) {
+        throw new Error(`AddonCallGateway: settings call to "${addonId}" missing method`)
+      }
+      return this.deps.broker.call(
+        `${addonId}.settings.${input.method}`,
+        (input.args ?? {}) as Record<string, unknown>,
+        opts,
+      )
+    }
+    // routes/custom are hub-local-child surfaces (mounted / invoked on the
+    // owning node); they are not proxied to a remote agent through this gateway.
+    throw new Error(`AddonCallGateway: target "${input.target}" not supported for remote agent "${baseNodeId}"`)
+  }
+
+  /**
+   * Resolve the Moleculer nodeID that actually hosts an addon's service.
+   * Forkable addons register under `${baseNodeId}/${addonId}`; in-process
+   * addons under the base nodeId. The registry is the ground truth — baseNodeId
+   * is a hint. (Moved verbatim from `addon-settings-provider.ts`.)
+   */
+  private resolveWorkerNodeId(addonId: string, baseNodeId: string): string | null {
+    const registry = this.deps.broker.registry
+    const services = (registry as unknown as {
+      getServiceList: (opts: { onlyAvailable: boolean }) => readonly { name: string; nodeID: string }[]
+    }).getServiceList({ onlyAvailable: true })
+    const exactNode = `${baseNodeId}/${addonId}`
+    const preferred = services.find((s) => s.name === addonId && s.nodeID === exactNode)
+    if (preferred) return preferred.nodeID
+    const anyForBase = services.find((s) => s.name === addonId && s.nodeID === baseNodeId)
+    if (anyForBase) return anyForBase.nodeID
+    const anyWithName = services.find((s) => s.name === addonId)
+    return anyWithName?.nodeID ?? null
+  }
+}

package/src/core/addon/addon-package.service.ts

@@ -1022,6 +1022,7 @@ export class AddonPackageService {
     readonly packageName: string
     readonly version?: string
     readonly requestedBy?: string
+    readonly deferRestart?: boolean
   }): Promise<{
     packageName: string
     fromVersion: string
@@ -1052,6 +1053,14 @@ export class AddonPackageService {
     const args = ['install', '--prefix', appRoot, spec, '--no-save', ...buildNpmRegistryArgs(registry)]
     await execFileAsync('npm', args, { timeout: 180_000 })
 
+    if (input.deferRestart === true) {
+      this.logger.info(
+        `updateFrameworkPackage(${packageName}@${toVersion}): install done, restart deferred`,
+      )
+      // Sentinel: 0 signals "no restart scheduled" to the caller
+      return { packageName, fromVersion, toVersion, restartingAt: 0 }
+    }
+
     const restartingAt = Date.now()
     const markerPayload: PendingRestartMarkerPayload = {
       kind: 'framework-update',