@dronedeploy/rocos-js-sdk 4.4.4 → 4.4.6

package/cjs/models/robot-status/RobotStatus.d.ts

@@ -41,3 +41,26 @@ export interface RobotStatus {
     connectivity: RobotConnectivityStatus;
     colour: RobotStatusColour;
 }
+/**
+ * One contributor to a reported-status axis, from the agent's
+ * `robot/status/contributors` topic. `status` is the contributor's own verdict
+ * for that axis — the integer wire value mapped onto the enum.
+ */
+export interface RobotStatusContributor<TStatus = RobotHealth | RobotReadiness> {
+    /** Identifier of the contributor, e.g. `battery`. */
+    id: string;
+    /** The agent component that raised it, e.g. `dji`. */
+    component: string;
+    /** Human-readable explanation, e.g. `battery below 20%`; empty when none was given. */
+    reason: string;
+    /** The contributor's verdict for its axis. */
+    status: TStatus;
+}
+/**
+ * The per-contributor breakdown behind a robot's reported health and readiness,
+ * from the agent's `robot/status/contributors` topic.
+ */
+export interface RobotStatusContributors {
+    health: RobotStatusContributor<RobotHealth>[];
+    readiness: RobotStatusContributor<RobotReadiness>[];
+}

package/cjs/models/robot-status/RobotStatusEnums.d.ts

@@ -30,13 +30,22 @@ export declare enum RobotReadiness {
     BUSY = "busy"
 }
 /**
- * Whether the robot is connected to a single cloud service, as reported by that
- * service's `connections` endpoint (or, for `telemetry-liveness`, derived from
- * heartbeat freshness).
+ * Whether the robot is connected to a single cloud service — reported by that
+ * service's `connections` endpoint, derived from heartbeat freshness (for
+ * `telemetry-liveness`), or supplied by a caller-injected signal
+ * (`RobotStatusOptions.extraServices`), the only source that can report {@link FAILED}.
  */
 export declare enum ServiceConnection {
     CONNECTED = "connected",
     DISCONNECTED = "disconnected",
+    /**
+     * The service reports an explicit fault — a stronger signal than {@link DISCONNECTED} (which just
+     * means "not connected", as expected of a robot that is simply off). A failed virtual-robot
+     * deployment is the motivating case. Any `FAILED` service forces the aggregate to
+     * {@link RobotConnectivity.DEGRADED}, so a fault raises attention even when nothing else is
+     * connected — see `aggregateConnectivity`.
+     */
+    FAILED = "failed",
     /** The service's connectivity has not yet been determined (e.g. not polled). */
     UNKNOWN = "unknown"
 }
@@ -45,10 +54,13 @@ export declare enum ServiceConnection {
  * expected services.
  */
 export declare enum RobotConnectivity {
-    /** At least one expected service is connected and none is disconnected. */
+    /** At least one expected service is connected and none is disconnected or failed. */
     ONLINE = "online",
-    /** Some, but not all, expected services report connected. */
+    /**
+     * Any service reports a fault ({@link ServiceConnection.FAILED}), or a genuine mix — some
+     * connected, some disconnected. A `FAILED` service forces this even when nothing is connected.
+     */
     DEGRADED = "degraded",
-    /** No expected service reports connected. */
+    /** Nothing connected, and nothing failed. */
     OFFLINE = "offline"
 }

package/cjs/models/robot-status/RobotStatusEnums.js

@@ -35,14 +35,23 @@ var RobotReadiness;
     RobotReadiness["BUSY"] = "busy";
 })(RobotReadiness || (exports.RobotReadiness = RobotReadiness = {}));
 /**
- * Whether the robot is connected to a single cloud service, as reported by that
- * service's `connections` endpoint (or, for `telemetry-liveness`, derived from
- * heartbeat freshness).
+ * Whether the robot is connected to a single cloud service — reported by that
+ * service's `connections` endpoint, derived from heartbeat freshness (for
+ * `telemetry-liveness`), or supplied by a caller-injected signal
+ * (`RobotStatusOptions.extraServices`), the only source that can report {@link FAILED}.
  */
 var ServiceConnection;
 (function (ServiceConnection) {
     ServiceConnection["CONNECTED"] = "connected";
     ServiceConnection["DISCONNECTED"] = "disconnected";
+    /**
+     * The service reports an explicit fault — a stronger signal than {@link DISCONNECTED} (which just
+     * means "not connected", as expected of a robot that is simply off). A failed virtual-robot
+     * deployment is the motivating case. Any `FAILED` service forces the aggregate to
+     * {@link RobotConnectivity.DEGRADED}, so a fault raises attention even when nothing else is
+     * connected — see `aggregateConnectivity`.
+     */
+    ServiceConnection["FAILED"] = "failed";
     /** The service's connectivity has not yet been determined (e.g. not polled). */
     ServiceConnection["UNKNOWN"] = "unknown";
 })(ServiceConnection || (exports.ServiceConnection = ServiceConnection = {}));
@@ -52,10 +61,13 @@ var ServiceConnection;
  */
 var RobotConnectivity;
 (function (RobotConnectivity) {
-    /** At least one expected service is connected and none is disconnected. */
+    /** At least one expected service is connected and none is disconnected or failed. */
     RobotConnectivity["ONLINE"] = "online";
-    /** Some, but not all, expected services report connected. */
+    /**
+     * Any service reports a fault ({@link ServiceConnection.FAILED}), or a genuine mix — some
+     * connected, some disconnected. A `FAILED` service forces this even when nothing is connected.
+     */
     RobotConnectivity["DEGRADED"] = "degraded";
-    /** No expected service reports connected. */
+    /** Nothing connected, and nothing failed. */
     RobotConnectivity["OFFLINE"] = "offline";
 })(RobotConnectivity || (exports.RobotConnectivity = RobotConnectivity = {}));

package/cjs/services/AssetStorageService.js

@@ -99,7 +99,12 @@ class AssetStorageService extends BaseServiceAbstract_1.BaseServiceAbstract {
      * @param signedURL
      */
     async listFlowAssets(projectId, flowId, flowInstance, parent = '/', signedURL = false) {
-        return this.callGet((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_FLOW_ASSET_PATH_URL, { url: this.config.url, projectId, flowId, flowInstance }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
+        return this.callGet((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_FLOW_ASSET_PATH_URL, {
+            url: this.config.url,
+            projectId,
+            flowId: encodeURIComponent(flowId),
+            flowInstance: encodeURIComponent(flowInstance),
+        }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
     }
     /**
      * List assets for a mission

package/cjs/services/BaseServiceAbstract.js

@@ -44,7 +44,7 @@ class BaseServiceAbstract {
                 requestConfig.body = JSON.stringify(payload);
                 requestConfig.headers = { ...requestConfig.headers, 'Content-Type': 'application/json' };
             }
-            return this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
+            return await this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
         }
         catch (e) {
             const message = errorMessage;

package/cjs/services/BaseStreamService.d.ts

@@ -1,3 +1,4 @@
+import { IAcquiredStream } from '../api/StreamRegister';
 import { IBaseService, IBaseStream, IRocosSDKConfig, IStreamConfig, SubscriberStatusEnum } from '../models';
 import { ISubscriberStatus } from '../models/ISubscriberStatus';
 import { Logger } from 'loglevel';
@@ -10,7 +11,17 @@ export declare abstract class BaseStreamService<T extends IBaseStream, C extends
     protected constructor(name: string, config: IRocosSDKConfig);
     getStatus(): boolean;
     protected initStream(stream: T): Promise<void>;
-    protected createStreamFromConfig(identifier: string, config: C, onAcquire?: (stream: T) => void): Promise<{
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    protected acquireStream(identifier: string, config: C): IAcquiredStream<T>;
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    protected createStreamFromConfig(identifier: string, config: C): Promise<{
         stream: T;
         isNew: boolean;
     }>;

package/cjs/services/BaseStreamService.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseStreamService = void 0;
+const StreamRegister_1 = require("../api/StreamRegister");
 const models_1 = require("../models");
 const RocosLogger_1 = require("../logger/RocosLogger");
 const RocosStore_1 = require("../store/RocosStore");
-const StreamRegister_1 = require("../api/StreamRegister");
 const rxjs_1 = require("rxjs");
 class BaseStreamService {
     constructor(name, config) {
@@ -32,40 +32,29 @@ class BaseStreamService {
         }
         authService.startTokenRefreshChecker();
     }
-    async createStreamFromConfig(identifier, config, onAcquire) {
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    acquireStream(identifier, config) {
         const identifierWithScope = StreamRegister_1.StreamRegister.getIdentifier(identifier, config.scope);
-        const streamRegister = StreamRegister_1.StreamRegister.getInstance();
-        let stream = streamRegister.getStream(identifierWithScope);
-        let isNew = false;
-        if (!stream) {
-            isNew = true;
-            stream = this.getStream(config);
+        return StreamRegister_1.StreamRegister.getInstance().acquireStream(identifierWithScope, () => {
+            const stream = this.getStream(config);
             stream.statusStream$.subscribe((msg) => {
                 this.status = msg === models_1.SubscriberStatusEnum.STOPPED || msg === models_1.SubscriberStatusEnum.ALIVE;
                 this.status$.next(msg);
             });
-            streamRegister.addStream(stream);
-        }
-        // Acquire synchronously with the lookup/registration above, before any await. A stream is
-        // stopped and deregistered the instant its refcount hits zero, so a deferred acquire can land on
-        // a dead instance — including a freshly-registered stream torn down during the init await below.
-        onAcquire?.(stream);
-        if (isNew) {
-            try {
-                await this.initStream(stream);
-            }
-            catch (e) {
-                // Evict eagerly, before the error reaches the subscriber, so a synchronous resubscribe
-                // can't re-acquire this uninitialised instance.
-                streamRegister.removeStream(stream);
-                throw e;
-            }
-            // If a concurrent teardown deregistered this stream during init, init() has opened a receiver
-            // on an instance nothing can reach; close it.
-            if (streamRegister.getStream(identifierWithScope) !== stream) {
-                stream.stopStream();
-            }
-        }
+            return stream;
+        }, (stream) => this.initStream(stream));
+    }
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    async createStreamFromConfig(identifier, config) {
+        const { stream, isNew, ready } = this.acquireStream(identifier, config);
+        await ready;
         return { stream, isNew };
     }
 }

package/cjs/services/EnvironmentService.d.ts

@@ -21,6 +21,10 @@ export declare class EnvironmentService extends BaseServiceAbstract implements I
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     set(projectId: string, scene: unknown): Promise<void>;
     /**

package/cjs/services/EnvironmentService.js

@@ -36,9 +36,13 @@ class EnvironmentService extends BaseServiceAbstract_1.BaseServiceAbstract {
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     async set(projectId, scene) {
-        return this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
+        return this.callPut((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
     }
     /**
      * Update Environment

package/cjs/services/MapService.d.ts

@@ -36,10 +36,22 @@ export declare class MapService extends BaseServiceAbstract implements IBaseServ
      */
     listDeployedMaps(projectId: string, callsign: string): Promise<Map[]>;
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     merge(projectId: string, maps: [string, string], options: {
         name: string;

package/cjs/services/MapService.js

@@ -55,26 +55,38 @@ class MapService extends BaseServiceAbstract_1.BaseServiceAbstract {
         return resp.maps;
     }
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     async merge(projectId, maps, options) {
         if (maps.length !== 2)
             throw new Error('You must provide two maps to merge.');
-        const payload = {
-            projectID: projectId,
-            mapIDLeft: maps[0],
-            mapIDRight: maps[1],
-            name: options.name,
-            description: options.description,
-            callsign: options.callsign,
-        };
-        return this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_MAPS_MERGE_URL, {
+        await this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_MAPS_UNION_URL, {
             url: this.config.url,
             projectId,
-        }, this.config.insecure), payload, 'Failed to merge maps.');
+        }, this.config.insecure), { targetMapId: options.name, sources: [maps[0], maps[1]] }, 'Failed to merge maps.');
+        if (options.description) {
+            try {
+                await this.updateMetadata(projectId, options.name, { description: options.description });
+            }
+            catch (e) {
+                this.logger.error(`Map ${options.name} was created but its description could not be set.`, e);
+            }
+        }
     }
     /** Returns a map in its canonical form
      *

package/cjs/services/RobotStatusService.d.ts

@@ -1,4 +1,4 @@
-import { IBaseService, IRocosSDKConfig, RobotConnectivityStatus, RobotStatus, RocosError } from '../models';
+import { IBaseService, IRocosSDKConfig, RobotConnectivityStatus, RobotStatus, RobotStatusContributors, RocosError, ServiceConnection } from '../models';
 import { Observable } from 'rxjs';
 import { ReportedRobotStatus } from './robot-status/reportedStatus';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
@@ -10,6 +10,23 @@ export interface RobotStatusOptions {
     heartbeatTimeoutMs?: number;
     /** How often the connections endpoints are polled (ms, floored internally). */
     connectivityPollMs?: number;
+    /**
+     * Extra per-robot connectivity signals, keyed by service id, folded into
+     * {@link RobotConnectivityStatus.services} and the aggregate on equal footing with the built-in
+     * services. Lets a caller inject a signal the SDK can't derive itself (e.g. virtual-robot
+     * deployment status); emit {@link ServiceConnection.FAILED} to surface a fault as `DEGRADED`.
+     *
+     * A key that collides with a built-in service id (`telemetry-liveness`, `robot-configs`,
+     * `robot-services`) is ignored in favour of the built-in.
+     *
+     * An error from an injected observable is contained as {@link ServiceConnection.UNKNOWN} so it
+     * can't tear down the overall status stream — but it is *terminal* for that signal: unlike the
+     * built-in HTTP poller (which recovers on its next tick), the errored observable is not
+     * resubscribed, so the service stays `UNKNOWN` for the life of the stream (and `getConnectivity`
+     * then waits out its timeout). To report a recoverable fault, emit `FAILED` / `UNKNOWN` as a
+     * value rather than letting the observable error.
+     */
+    extraServices?: Record<string, Observable<ServiceConnection>>;
 }
 /**
  * The single source of truth for a robot's status. It composes the reported
@@ -22,6 +39,8 @@ export declare class RobotStatusService extends BaseServiceAbstract implements I
     getStatus(): boolean;
     /** Health + readiness as reported by the robot (new topic, legacy heartbeat fallback). */
     getReportedStatusChanges(projectId: string, callsign: string): Observable<ReportedRobotStatus>;
+    /** Per-contributor breakdown behind the reported health and readiness, with the reason for each. */
+    getStatusContributorsChanges(projectId: string, callsign: string): Observable<RobotStatusContributors>;
     /** Per-service connectivity plus the aggregate verdict, polled. */
     getConnectivityChanges(projectId: string, callsign: string, opts?: RobotStatusOptions): Observable<RobotConnectivityStatus>;
     /** One-shot connectivity snapshot: resolves once every expected service is known, or after a timeout. */

package/cjs/services/RobotStatusService.js

@@ -42,6 +42,10 @@ class RobotStatusService extends BaseServiceAbstract_1.BaseServiceAbstract {
     getReportedStatusChanges(projectId, callsign) {
         return (0, reportedStatus_1.getReportedStatusChanges)(this.telemetryService, projectId, callsign);
     }
+    /** Per-contributor breakdown behind the reported health and readiness, with the reason for each. */
+    getStatusContributorsChanges(projectId, callsign) {
+        return (0, reportedStatus_1.getStatusContributorsChanges)(this.telemetryService, projectId, callsign);
+    }
     /** Per-service connectivity plus the aggregate verdict, polled. */
     getConnectivityChanges(projectId, callsign, opts) {
         return (0, connectivity_1.getConnectivityChanges)(this.connectivityDeps(projectId, callsign, opts), projectId, callsign, opts?.expectedServices, opts?.connectivityPollMs);
@@ -88,6 +92,7 @@ class RobotStatusService extends BaseServiceAbstract_1.BaseServiceAbstract {
             baseUrl: this.config.url,
             insecure: this.config.insecure,
             telemetryLiveness$: (0, reportedStatus_1.getTelemetryLiveness)(this.telemetryService, projectId, callsign, opts?.heartbeatTimeoutMs),
+            extraServices: opts?.extraServices,
         };
     }
 }

package/cjs/services/SearchService.js

@@ -39,7 +39,7 @@ class SearchService extends BaseStreamService_1.BaseStreamService {
         return stream.deleteProjectData(params);
     }
     async createStream() {
-        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_FILE_ACCESSOR, {
+        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_SEARCH, {
             url: this.config.url,
             token: this.config.token,
             scope: 'default',

package/cjs/services/TargetService.js

@@ -56,10 +56,10 @@ class TargetService extends BaseServiceAbstract_1.BaseServiceAbstract {
         });
     }
     async addMedia(projectId, targetId, media) {
-        await this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_TARGETS_URL, {
+        await this.callPut((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_TARGET_MEDIA_URL, {
             url: this.config.url,
             projectId,
-            targetId,
+            targetId: encodeURIComponent(targetId),
         }, this.config.insecure), media, 'Failed to add media to a target');
     }
 }

package/cjs/services/TelemetryService.d.ts

@@ -3,7 +3,6 @@ import { CallsignStatus, IRocosSDKConfig, IRocosTelemetryMessage, IStreamStatusM
 import { BaseStreamService } from './BaseStreamService';
 export declare class TelemetryService extends BaseStreamService<ITelemetryStream, ITelemetryStreamConfig> {
     private static grpcWebDeprecationWarned;
-    private statusSubscription;
     private changeStream$;
     private streamStatusSubject$;
     constructor(config: IRocosSDKConfig);
@@ -46,6 +45,6 @@ export declare class TelemetryService extends BaseStreamService<ITelemetryStream
     monitorTelemetryWithTimeout(projectId: string, callsign: string, source: string, heartbeatTimeoutMs?: number, intervalMs?: number): Observable<TelemetryMonitorStatus>;
     protected initStream(stream: ITelemetryStream): Promise<void>;
     private buildScope;
-    private createStream;
+    private buildStreamConfig;
     protected getStream(config: ITelemetryStreamConfig): ITelemetryStream;
 }

package/cjs/services/TelemetryService.js

@@ -55,31 +55,42 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
         // scope is used as a key to generate unique streams
         // ideally there should be just one concurrent stream opened
         const scope = this.buildScope(params, callsignsLookup);
-        const callsigns = callsignsLookup.lookupValue;
         const subscriptionParams = {
             uniqueId: (0, getUniqueId_1.getUniqueId)(params.projectId, callsignsLookup, sources, scope),
-            callsigns: callsignsLookup?.lookupType === models_1.CallsignsLookupType.List ? callsignsLookup.lookupValue : [],
+            callsigns: callsignsLookup.getCallsigns(),
             sources,
         };
         // `defer` acquires the stream only when subscribed; `finalize` releases it on unsubscribe, error
-        // and complete — so acquire and release stay balanced on every path.
+        // and complete — so acquire and release stay balanced on every path. The registry refcount taken
+        // here keeps the stream alive until the finalize, so everything in between is race-free.
         return (0, rxjs_1.defer)(() => {
-            let acquired;
-            const stream$ = this.createStream(params.projectId, callsignsLookup, sources, scope, (stream) => {
-                acquired = stream;
+            const { stream, isNew, ready, release } = this.acquireStream(identifier_1.IDENTIFIER_NAME_TELEMETRY, this.buildStreamConfig(params.projectId, callsignsLookup, sources, scope));
+            try {
                 stream.addSubscription(subscriptionParams);
-            }).then((stream) => {
-                if (!this.statusSubscription) {
-                    this.statusSubscription = stream.statusStream$.subscribe((msg) => {
-                        this.status = msg === models_1.SubscriberStatusEnum.STOPPED || msg === models_1.SubscriberStatusEnum.ALIVE;
-                        this.status$.next(msg);
+                // Forward the stream's status onto the per-scope subject once, at creation; it ends when the
+                // stream stops (statusStream$ completes), so it is not re-created or leaked across subscribers.
+                if (isNew) {
+                    stream.statusStream$.subscribe((msg) => {
+                        this.streamStatusSubject$.next({
+                            scope,
+                            status: msg,
+                        });
                     });
                 }
-                return (0, rxjs_1.from)(stream.messageStream$);
-            });
-            return (0, rxjs_1.from)(stream$).pipe((0, rxjs_1.mergeAll)(), (0, operators_1.filter)((message) => {
-                return callsigns.includes(message.callsign) && sources.includes(message.source);
-            }), (0, operators_1.finalize)(() => acquired?.removeSubscription(subscriptionParams, params.terminateReceiverGroupOnUnsubscribe)));
+            }
+            catch (e) {
+                // finalize below is not wired up yet, so a throw here must hand the refcount back itself.
+                release();
+                throw e;
+            }
+            // status$ / getStatus() are driven by the acquireStream factory (BaseStreamService), not here.
+            const messages$ = ready.then(() => (0, rxjs_1.from)(stream.messageStream$));
+            return (0, rxjs_1.from)(messages$).pipe((0, rxjs_1.mergeAll)(), (0, operators_1.filter)((message) => {
+                return callsignsLookup.includesCallsign(message.callsign) && sources.includes(message.source);
+            }), (0, operators_1.finalize)(() => {
+                void stream.removeSubscription(subscriptionParams, params.terminateReceiverGroupOnUnsubscribe);
+                release();
+            }));
         });
     }
     /**
@@ -159,8 +170,8 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
             return `${params.projectId}-default-${(0, flattenCallsignsLookup_1.flattenCallsignsLookup)(callsignsLookup).join()}`;
         return `${params.projectId}-default`;
     }
-    async createStream(projectId, callsignsLookup, sources, scope, onAcquire) {
-        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_TELEMETRY, {
+    buildStreamConfig(projectId, callsignsLookup, sources, scope) {
+        return {
             url: this.config.url,
             projectId,
             callsignsLookup,
@@ -172,16 +183,7 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
             insecure: this.config.insecure,
             transport: this.config.transport,
             fetch: this.config.fetch,
-        }, onAcquire);
-        if (!newStream.isNew) {
-            newStream.stream.statusStream$.subscribe((msg) => {
-                this.streamStatusSubject$.next({
-                    scope,
-                    status: msg,
-                });
-            });
-        }
-        return newStream.stream;
+        };
     }
     getStream(config) {
         if (config.transport === 'grpc-web') {

package/cjs/services/WebRTCSignallingService.js

@@ -37,11 +37,9 @@ class WebRTCSignallingService {
     }
     async createSignallingStream() {
         const scope = 'default';
-        const identifier = StreamRegister_1.StreamRegister.getIdentifier(identifier_1.IDENTIFIER_NAME_COMMAND, scope);
-        const streamRegister = StreamRegister_1.StreamRegister.getInstance();
-        let stream = streamRegister.getStream(identifier);
-        if (!stream) {
-            stream = this.getStream({
+        const identifier = StreamRegister_1.StreamRegister.getIdentifier(identifier_1.IDENTIFIER_NAME_WEBRTC_SIGNALLING, scope);
+        const { stream, ready } = StreamRegister_1.StreamRegister.getInstance().acquireStream(identifier, () => {
+            const newStream = this.getStream({
                 url: this.config.url,
                 token: this.config.token,
                 scope,
@@ -49,13 +47,13 @@ class WebRTCSignallingService {
                 port: this.config.port,
                 insecure: this.config.insecure,
             });
-            stream.statusStream$.subscribe((msg) => {
+            newStream.statusStream$.subscribe((msg) => {
                 this.status = msg === SubscriberStatusEnum_1.SubscriberStatusEnum.STOPPED || msg === SubscriberStatusEnum_1.SubscriberStatusEnum.ALIVE;
                 this.status$.next(msg);
             });
-            streamRegister.addStream(stream);
-            await this.initStream(stream);
-        }
+            return newStream;
+        }, (newStream) => this.initStream(newStream));
+        await ready;
         return stream;
     }
     async initStream(stream) {

package/cjs/services/robot-status/connectivity.d.ts

@@ -36,18 +36,19 @@ export declare const buildConnectionsUrl: (serviceId: string, baseUrl: string, p
 export declare const mapConnectionStatus: (connection?: IConnectedCallsign | null) => ServiceConnection;
 /**
  * Aggregates per-service connection states into an overall verdict:
- * - `ONLINE`   — at least one service connected and none disconnected.
- * - `DEGRADED` — a genuine mix: some connected, some disconnected.
+ * - `DEGRADED` — any service reports an explicit `FAILED` fault, or a genuine mix (some connected,
+ *                some disconnected).
+ * - `ONLINE`   — at least one service connected and none disconnected or failed.
  * - `OFFLINE`  — nothing connected.
  *
- * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup
- * settles on `OFFLINE` (gray) rather than a spurious flashing-red degraded state.
+ * A `FAILED` service forces `DEGRADED` even when nothing else is connected, so a fault (e.g. a failed
+ * deployment) raises attention rather than reading as a plain, switched-off `OFFLINE`.
  *
- * Note: this optimism also means a service held `UNKNOWN` indefinitely (e.g. an
- * endpoint whose polls keep failing) does not by itself pull the aggregate below
- * `ONLINE` — a deliberate v1 tradeoff to keep transient errors from flapping the
- * indicator. Surfacing a long-lived failure distinctly (likely via health rather
- * than connectivity) is left as a future refinement.
+ * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup settles on `OFFLINE`
+ * (gray) rather than a spurious flashing-red degraded state. This optimism also means a service held
+ * `UNKNOWN` indefinitely (e.g. an endpoint whose polls keep failing) does not by itself pull the
+ * aggregate below `ONLINE` — a deliberate tradeoff to keep transient errors from flapping the
+ * indicator; a service that wants to be surfaced reports `FAILED` explicitly.
  */
 export declare const aggregateConnectivity: (services: Record<string, ServiceConnection>) => RobotConnectivity;
 /**
@@ -66,11 +67,14 @@ export interface ConnectivityDeps {
     insecure?: boolean;
     /** The telemetry-liveness signal (from `getTelemetryLiveness`), folded in as one service. */
     telemetryLiveness$: Observable<ServiceConnection>;
+    /** Caller-injected connectivity signals, keyed by service id, folded in on equal footing. */
+    extraServices?: Record<string, Observable<ServiceConnection>>;
 }
 /**
  * Emits the robot's {@link RobotConnectivityStatus} — the per-service breakdown
- * plus the aggregate verdict — for the configured `expectedServices`. HTTP
- * services are polled; `telemetry-liveness` uses the supplied observable; any
- * unrecognised service id resolves to `UNKNOWN`.
+ * plus the aggregate verdict — for the configured `expectedServices`, plus any
+ * caller-injected `extraServices` (folded in on equal footing). HTTP services
+ * are polled; `telemetry-liveness` and injected services use their supplied
+ * observable; any unrecognised service id resolves to `UNKNOWN`.
  */
 export declare const getConnectivityChanges: (deps: ConnectivityDeps, projectId: string, callsign: string, expectedServices?: string[], pollMs?: number) => Observable<RobotConnectivityStatus>;