@dronedeploy/rocos-js-sdk 4.4.5 → 4.4.6

package/cjs/api/streams/telemetry/TelemetryStreamAbstract.js

@@ -62,6 +62,10 @@ class TelemetryStreamAbstract {
         }
         this.subscriberStatus = models_1.SubscriberStatusEnum.STOPPED;
         this.statusStream$.next(this.subscriberStatus);
+        // The stream is being torn down (the registry only stops a stream when it is evicted), so
+        // complete the status stream: this releases every service-level forwarder subscribed to it
+        // rather than leaving them attached to a dead instance.
+        this.statusStream$.complete();
     }
     addSubscription(params) {
         this.logger.info('Adding subscriptions from stream', params.uniqueId);

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/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/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);

package/cjs/services/TelemetryService.js

@@ -67,7 +67,9 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
             const { stream, isNew, ready, release } = this.acquireStream(identifier_1.IDENTIFIER_NAME_TELEMETRY, this.buildStreamConfig(params.projectId, callsignsLookup, sources, scope));
             try {
                 stream.addSubscription(subscriptionParams);
-                if (!isNew) {
+                // 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,
@@ -81,15 +83,8 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
                 release();
                 throw e;
             }
-            const messages$ = ready.then(() => {
-                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);
-                    });
-                }
-                return (0, rxjs_1.from)(stream.messageStream$);
-            });
+            // 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)(() => {

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>;

package/cjs/services/robot-status/connectivity.js

@@ -58,21 +58,24 @@ const mapConnectionStatus = (connection) => {
 exports.mapConnectionStatus = mapConnectionStatus;
 /**
  * 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.
  */
 const aggregateConnectivity = (services) => {
     const values = Object.values(services);
+    if (values.includes(models_1.ServiceConnection.FAILED))
+        return models_1.RobotConnectivity.DEGRADED;
     const hasConnected = values.includes(models_1.ServiceConnection.CONNECTED);
     const hasDisconnected = values.includes(models_1.ServiceConnection.DISCONNECTED);
     if (hasConnected && hasDisconnected)
@@ -107,24 +110,32 @@ const connectivityEquals = (a, b) => {
 };
 /**
  * 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`.
  */
 const getConnectivityChanges = (deps, projectId, callsign, expectedServices = exports.DEFAULT_EXPECTED_SERVICES, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    const extraServices = deps.extraServices ?? {};
+    const serviceIds = [...expectedServices, ...Object.keys(extraServices).filter((id) => !expectedServices.includes(id))];
     // combineLatest([]) completes without emitting; emit an explicit empty/offline status instead.
-    if (expectedServices.length === 0) {
+    if (serviceIds.length === 0) {
         return (0, rxjs_1.of)({ overall: models_1.RobotConnectivity.OFFLINE, services: {} });
     }
-    const perService = expectedServices.map((serviceId) => {
+    const perService = serviceIds.map((serviceId) => {
         let source$;
         if (serviceId === exports.TELEMETRY_LIVENESS_SERVICE) {
             source$ = deps.telemetryLiveness$;
         }
-        else if (serviceId in exports.CONNECTION_SERVICE_PREFIXES) {
+        else if (Object.prototype.hasOwnProperty.call(exports.CONNECTION_SERVICE_PREFIXES, serviceId)) {
             const url = (0, exports.buildConnectionsUrl)(serviceId, deps.baseUrl, projectId, callsign, deps.insecure);
             source$ = (0, exports.getServiceConnectionChanges)(deps.httpGet, url, pollMs);
         }
+        else if (Object.prototype.hasOwnProperty.call(extraServices, serviceId)) {
+            // Contain an injected observable's errors as UNKNOWN, mirroring the built-in sources, so a
+            // faulty caller signal can't error out combineLatest and tear down the whole aggregate.
+            source$ = extraServices[serviceId].pipe((0, rxjs_1.catchError)(() => (0, rxjs_1.of)(models_1.ServiceConnection.UNKNOWN)));
+        }
         else {
             source$ = (0, rxjs_1.of)(models_1.ServiceConnection.UNKNOWN);
         }

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

@@ -1,10 +1,12 @@
 import { Observable } from 'rxjs';
-import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+import { RobotHealth, RobotReadiness, RobotStatusContributors, ServiceConnection } from '../../models';
 import { TelemetryService } from '../TelemetryService';
 /** The new agent topic carrying health + readiness (replaces the heartbeat). */
 export declare const ROBOT_STATUS_SOURCE = "/diagnostics/robot/status";
 /** The legacy heartbeat topic — liveness only, no status payload. */
 export declare const LEGACY_HEARTBEAT_SOURCE = "/rocos/agent/telemetry/heartbeat";
+/** The per-contributor breakdown behind the reported status (health + readiness). */
+export declare const ROBOT_STATUS_CONTRIBUTORS_SOURCE = "/diagnostics/robot/status/contributors";
 export interface ReportedRobotStatus {
     health: RobotHealth;
     readiness: RobotReadiness;
@@ -28,6 +30,17 @@ export declare const parseRobotReadiness: (value: unknown) => RobotReadiness;
  * new topic.
  */
 export declare const getReportedStatusChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<ReportedRobotStatus>;
+/**
+ * Emits the per-contributor breakdown behind the robot's reported health and
+ * readiness, from the agent's `robot/status/contributors` topic. Each
+ * contributor's integer wire value is mapped onto {@link RobotHealth} /
+ * {@link RobotReadiness}; a missing `health`/`readiness` array becomes `[]`.
+ *
+ * Starts with an empty breakdown so consumers combining this with other streams
+ * emit immediately, and — like {@link getReportedStatusChanges} — a telemetry
+ * error falls back to an empty breakdown rather than terminating the stream.
+ */
+export declare const getStatusContributorsChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<RobotStatusContributors>;
 /**
  * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
  * either the new `robot/status` topic or the legacy heartbeat) has been received

package/cjs/services/robot-status/reportedStatus.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTelemetryLiveness = exports.getReportedStatusChanges = exports.parseRobotReadiness = exports.parseRobotHealth = exports.LEGACY_HEARTBEAT_SOURCE = exports.ROBOT_STATUS_SOURCE = void 0;
+exports.getTelemetryLiveness = exports.getStatusContributorsChanges = exports.getReportedStatusChanges = exports.parseRobotReadiness = exports.parseRobotHealth = exports.ROBOT_STATUS_CONTRIBUTORS_SOURCE = exports.LEGACY_HEARTBEAT_SOURCE = exports.ROBOT_STATUS_SOURCE = void 0;
 const rxjs_1 = require("rxjs");
 const models_1 = require("../../models");
 /** The new agent topic carrying health + readiness (replaces the heartbeat). */
 exports.ROBOT_STATUS_SOURCE = '/diagnostics/robot/status';
 /** The legacy heartbeat topic — liveness only, no status payload. */
 exports.LEGACY_HEARTBEAT_SOURCE = '/rocos/agent/telemetry/heartbeat';
+/** The per-contributor breakdown behind the reported status (health + readiness). */
+exports.ROBOT_STATUS_CONTRIBUTORS_SOURCE = `${exports.ROBOT_STATUS_SOURCE}/contributors`;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5000;
 const DEFAULT_INTERVAL_MS = 2000;
 /**
@@ -84,6 +86,39 @@ const getReportedStatusChanges = (telemetry, projectId, callsign) => {
     (0, rxjs_1.catchError)(() => (0, rxjs_1.of)({ health: models_1.RobotHealth.UNKNOWN, readiness: models_1.RobotReadiness.UNKNOWN })));
 };
 exports.getReportedStatusChanges = getReportedStatusChanges;
+const toContributor = (raw, parse) => ({
+    id: raw.id ?? '',
+    component: raw.component ?? '',
+    reason: raw.reason ?? '',
+    status: parse(raw.value),
+});
+const EMPTY_CONTRIBUTORS = { health: [], readiness: [] };
+/**
+ * Emits the per-contributor breakdown behind the robot's reported health and
+ * readiness, from the agent's `robot/status/contributors` topic. Each
+ * contributor's integer wire value is mapped onto {@link RobotHealth} /
+ * {@link RobotReadiness}; a missing `health`/`readiness` array becomes `[]`.
+ *
+ * Starts with an empty breakdown so consumers combining this with other streams
+ * emit immediately, and — like {@link getReportedStatusChanges} — a telemetry
+ * error falls back to an empty breakdown rather than terminating the stream.
+ */
+const getStatusContributorsChanges = (telemetry, projectId, callsign) => {
+    return telemetry
+        .subscribe({
+        projectId,
+        callsigns: [callsign],
+        sources: [exports.ROBOT_STATUS_CONTRIBUTORS_SOURCE],
+    })
+        .pipe((0, rxjs_1.map)((message) => {
+        const payload = message.payload ?? {};
+        return {
+            health: (payload.health ?? []).map((c) => toContributor(c, exports.parseRobotHealth)),
+            readiness: (payload.readiness ?? []).map((c) => toContributor(c, exports.parseRobotReadiness)),
+        };
+    }), (0, rxjs_1.startWith)(EMPTY_CONTRIBUTORS), (0, rxjs_1.distinctUntilChanged)((a, b) => JSON.stringify(a) === JSON.stringify(b)), (0, rxjs_1.catchError)(() => (0, rxjs_1.of)(EMPTY_CONTRIBUTORS)));
+};
+exports.getStatusContributorsChanges = getStatusContributorsChanges;
 /**
  * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
  * either the new `robot/status` topic or the legacy heartbeat) has been received

package/esm/api/streams/telemetry/TelemetryStreamAbstract.js

@@ -59,6 +59,10 @@ export class TelemetryStreamAbstract {
         }
         this.subscriberStatus = SubscriberStatusEnum.STOPPED;
         this.statusStream$.next(this.subscriberStatus);
+        // The stream is being torn down (the registry only stops a stream when it is evicted), so
+        // complete the status stream: this releases every service-level forwarder subscribed to it
+        // rather than leaving them attached to a dead instance.
+        this.statusStream$.complete();
     }
     addSubscription(params) {
         this.logger.info('Adding subscriptions from stream', params.uniqueId);

package/esm/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/esm/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/esm/models/robot-status/RobotStatusEnums.js

@@ -32,14 +32,23 @@ export var RobotReadiness;
     RobotReadiness["BUSY"] = "busy";
 })(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}.
  */
 export 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 || (ServiceConnection = {}));
@@ -49,10 +58,13 @@ export var ServiceConnection;
  */
 export 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 || (RobotConnectivity = {}));

package/esm/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/esm/services/RobotStatusService.js

@@ -1,7 +1,7 @@
 import { getConnectivityChanges } from './robot-status/connectivity';
 import { RobotHealth, RobotReadiness, RocosError, ServiceConnection, errorCodes, } from '../models';
 import { combineLatest, distinctUntilChanged, first, firstValueFrom, map, of, shareReplay, startWith, take, tap, timeout, } from 'rxjs';
-import { getReportedStatusChanges, getTelemetryLiveness } from './robot-status/reportedStatus';
+import { getReportedStatusChanges, getStatusContributorsChanges, getTelemetryLiveness, } from './robot-status/reportedStatus';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 import { RocosLogger } from '../logger/RocosLogger';
 import { RocosStore } from '../store/RocosStore';
@@ -39,6 +39,10 @@ export class RobotStatusService extends BaseServiceAbstract {
     getReportedStatusChanges(projectId, callsign) {
         return getReportedStatusChanges(this.telemetryService, projectId, callsign);
     }
+    /** Per-contributor breakdown behind the reported health and readiness, with the reason for each. */
+    getStatusContributorsChanges(projectId, callsign) {
+        return getStatusContributorsChanges(this.telemetryService, projectId, callsign);
+    }
     /** Per-service connectivity plus the aggregate verdict, polled. */
     getConnectivityChanges(projectId, callsign, opts) {
         return getConnectivityChanges(this.connectivityDeps(projectId, callsign, opts), projectId, callsign, opts?.expectedServices, opts?.connectivityPollMs);
@@ -85,6 +89,7 @@ export class RobotStatusService extends BaseServiceAbstract {
             baseUrl: this.config.url,
             insecure: this.config.insecure,
             telemetryLiveness$: getTelemetryLiveness(this.telemetryService, projectId, callsign, opts?.heartbeatTimeoutMs),
+            extraServices: opts?.extraServices,
         };
     }
 }

package/esm/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);

package/esm/services/TelemetryService.js

@@ -64,7 +64,9 @@ export class TelemetryService extends BaseStreamService {
             const { stream, isNew, ready, release } = this.acquireStream(IDENTIFIER_NAME_TELEMETRY, this.buildStreamConfig(params.projectId, callsignsLookup, sources, scope));
             try {
                 stream.addSubscription(subscriptionParams);
-                if (!isNew) {
+                // 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,
@@ -78,15 +80,8 @@ export class TelemetryService extends BaseStreamService {
                 release();
                 throw e;
             }
-            const messages$ = ready.then(() => {
-                if (!this.statusSubscription) {
-                    this.statusSubscription = stream.statusStream$.subscribe((msg) => {
-                        this.status = msg === SubscriberStatusEnum.STOPPED || msg === SubscriberStatusEnum.ALIVE;
-                        this.status$.next(msg);
-                    });
-                }
-                return from(stream.messageStream$);
-            });
+            // status$ / getStatus() are driven by the acquireStream factory (BaseStreamService), not here.
+            const messages$ = ready.then(() => from(stream.messageStream$));
             return from(messages$).pipe(mergeAll(), filter((message) => {
                 return callsignsLookup.includesCallsign(message.callsign) && sources.includes(message.source);
             }), finalize(() => {

package/esm/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>;

package/esm/services/robot-status/connectivity.js

@@ -52,21 +52,24 @@ export const mapConnectionStatus = (connection) => {
 };
 /**
  * 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 const aggregateConnectivity = (services) => {
     const values = Object.values(services);
+    if (values.includes(ServiceConnection.FAILED))
+        return RobotConnectivity.DEGRADED;
     const hasConnected = values.includes(ServiceConnection.CONNECTED);
     const hasDisconnected = values.includes(ServiceConnection.DISCONNECTED);
     if (hasConnected && hasDisconnected)
@@ -99,24 +102,32 @@ const connectivityEquals = (a, b) => {
 };
 /**
  * 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 const getConnectivityChanges = (deps, projectId, callsign, expectedServices = DEFAULT_EXPECTED_SERVICES, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    const extraServices = deps.extraServices ?? {};
+    const serviceIds = [...expectedServices, ...Object.keys(extraServices).filter((id) => !expectedServices.includes(id))];
     // combineLatest([]) completes without emitting; emit an explicit empty/offline status instead.
-    if (expectedServices.length === 0) {
+    if (serviceIds.length === 0) {
         return of({ overall: RobotConnectivity.OFFLINE, services: {} });
     }
-    const perService = expectedServices.map((serviceId) => {
+    const perService = serviceIds.map((serviceId) => {
         let source$;
         if (serviceId === TELEMETRY_LIVENESS_SERVICE) {
             source$ = deps.telemetryLiveness$;
         }
-        else if (serviceId in CONNECTION_SERVICE_PREFIXES) {
+        else if (Object.prototype.hasOwnProperty.call(CONNECTION_SERVICE_PREFIXES, serviceId)) {
             const url = buildConnectionsUrl(serviceId, deps.baseUrl, projectId, callsign, deps.insecure);
             source$ = getServiceConnectionChanges(deps.httpGet, url, pollMs);
         }
+        else if (Object.prototype.hasOwnProperty.call(extraServices, serviceId)) {
+            // Contain an injected observable's errors as UNKNOWN, mirroring the built-in sources, so a
+            // faulty caller signal can't error out combineLatest and tear down the whole aggregate.
+            source$ = extraServices[serviceId].pipe(catchError(() => of(ServiceConnection.UNKNOWN)));
+        }
         else {
             source$ = of(ServiceConnection.UNKNOWN);
         }

package/esm/services/robot-status/reportedStatus.d.ts

@@ -1,10 +1,12 @@
 import { Observable } from 'rxjs';
-import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+import { RobotHealth, RobotReadiness, RobotStatusContributors, ServiceConnection } from '../../models';
 import { TelemetryService } from '../TelemetryService';
 /** The new agent topic carrying health + readiness (replaces the heartbeat). */
 export declare const ROBOT_STATUS_SOURCE = "/diagnostics/robot/status";
 /** The legacy heartbeat topic — liveness only, no status payload. */
 export declare const LEGACY_HEARTBEAT_SOURCE = "/rocos/agent/telemetry/heartbeat";
+/** The per-contributor breakdown behind the reported status (health + readiness). */
+export declare const ROBOT_STATUS_CONTRIBUTORS_SOURCE = "/diagnostics/robot/status/contributors";
 export interface ReportedRobotStatus {
     health: RobotHealth;
     readiness: RobotReadiness;
@@ -28,6 +30,17 @@ export declare const parseRobotReadiness: (value: unknown) => RobotReadiness;
  * new topic.
  */
 export declare const getReportedStatusChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<ReportedRobotStatus>;
+/**
+ * Emits the per-contributor breakdown behind the robot's reported health and
+ * readiness, from the agent's `robot/status/contributors` topic. Each
+ * contributor's integer wire value is mapped onto {@link RobotHealth} /
+ * {@link RobotReadiness}; a missing `health`/`readiness` array becomes `[]`.
+ *
+ * Starts with an empty breakdown so consumers combining this with other streams
+ * emit immediately, and — like {@link getReportedStatusChanges} — a telemetry
+ * error falls back to an empty breakdown rather than terminating the stream.
+ */
+export declare const getStatusContributorsChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<RobotStatusContributors>;
 /**
  * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
  * either the new `robot/status` topic or the legacy heartbeat) has been received

package/esm/services/robot-status/reportedStatus.js

@@ -1,9 +1,11 @@
 import { catchError, combineLatest, distinctUntilChanged, filter, interval, map, merge, of, scan, startWith, } from 'rxjs';
-import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+import { RobotHealth, RobotReadiness, ServiceConnection, } from '../../models';
 /** The new agent topic carrying health + readiness (replaces the heartbeat). */
 export const ROBOT_STATUS_SOURCE = '/diagnostics/robot/status';
 /** The legacy heartbeat topic — liveness only, no status payload. */
 export const LEGACY_HEARTBEAT_SOURCE = '/rocos/agent/telemetry/heartbeat';
+/** The per-contributor breakdown behind the reported status (health + readiness). */
+export const ROBOT_STATUS_CONTRIBUTORS_SOURCE = `${ROBOT_STATUS_SOURCE}/contributors`;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5000;
 const DEFAULT_INTERVAL_MS = 2000;
 /**
@@ -78,6 +80,38 @@ export const getReportedStatusChanges = (telemetry, projectId, callsign) => {
     // UNKNOWN/UNKNOWN (matching getTelemetryLiveness) so subscribers get an honest value.
     catchError(() => of({ health: RobotHealth.UNKNOWN, readiness: RobotReadiness.UNKNOWN })));
 };
+const toContributor = (raw, parse) => ({
+    id: raw.id ?? '',
+    component: raw.component ?? '',
+    reason: raw.reason ?? '',
+    status: parse(raw.value),
+});
+const EMPTY_CONTRIBUTORS = { health: [], readiness: [] };
+/**
+ * Emits the per-contributor breakdown behind the robot's reported health and
+ * readiness, from the agent's `robot/status/contributors` topic. Each
+ * contributor's integer wire value is mapped onto {@link RobotHealth} /
+ * {@link RobotReadiness}; a missing `health`/`readiness` array becomes `[]`.
+ *
+ * Starts with an empty breakdown so consumers combining this with other streams
+ * emit immediately, and — like {@link getReportedStatusChanges} — a telemetry
+ * error falls back to an empty breakdown rather than terminating the stream.
+ */
+export const getStatusContributorsChanges = (telemetry, projectId, callsign) => {
+    return telemetry
+        .subscribe({
+        projectId,
+        callsigns: [callsign],
+        sources: [ROBOT_STATUS_CONTRIBUTORS_SOURCE],
+    })
+        .pipe(map((message) => {
+        const payload = message.payload ?? {};
+        return {
+            health: (payload.health ?? []).map((c) => toContributor(c, parseRobotHealth)),
+            readiness: (payload.readiness ?? []).map((c) => toContributor(c, parseRobotReadiness)),
+        };
+    }), startWith(EMPTY_CONTRIBUTORS), distinctUntilChanged((a, b) => JSON.stringify(a) === JSON.stringify(b)), catchError(() => of(EMPTY_CONTRIBUTORS)));
+};
 /**
  * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
  * either the new `robot/status` topic or the legacy heartbeat) has been received

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dronedeploy/rocos-js-sdk",
-  "version": "4.4.5",
+  "version": "4.4.6",
   "description": "Javascript SDK for rocos",
   "main": "cjs/index.js",
   "module": "esm/index.js",
@@ -42,5 +42,10 @@
     }
   },
   "repository": {},
-  "private": false
+  "private": false,
+  "overrides": {
+    "openapi-typescript": {
+      "typescript": "$typescript"
+    }
+  }
 }