@dg-kit/safety 1.14.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './contracts.js';
+export * from './policy-engine.js';
+export * from './default-policies.js';
+export * from './device-command-queue.js';
+export * from './safety-bus.js';
+export * from './lifecycle-guard.js';
+export * from './safety-notice-content.js';
+export * from './safety-acceptance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+// @dg-kit/safety — the single source of truth for the device safety chain.
+//
+// Policy engine (strength caps / cold-start clamp / burst-specific caps /
+// cumulative ceiling), default policies, and the serial command queue (with
+// emergency-stop preemption and generation invalidation). Before the merge
+// DG-Agent and DG-Voice each held a copy; stripped of imports and comments
+// the two were byte-identical, so merging involved no behavioral judgment
+// calls.
+export * from './contracts.js';
+export * from './policy-engine.js';
+export * from './default-policies.js';
+export * from './device-command-queue.js';
+export * from './safety-bus.js';
+export * from './lifecycle-guard.js';
+export * from './safety-notice-content.js';
+export * from './safety-acceptance.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,SAAS;AACT,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC"}

package/dist/lifecycle-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stops device output when the page goes away or into the background.
+ *
+ * There used to be two of these — DG-Agent's `BrowserSafetyGuard` and
+ * DG-Voice's `CallSafetyGuard`, near-identical down to the in-flight guard
+ * and the listener set. They differed in exactly one way: Agent made
+ * "keep running while backgrounded" a user setting, Voice always stopped.
+ *
+ * This keeps Voice's behavior, for everyone. Screen off or tab away means
+ * stop, unconditionally, and there is no option to turn that off — which is
+ * also why the two can now be one class without the earlier worry that a
+ * wrong default would quietly ship "keeps firing while backgrounded" to a
+ * module whose author never chose it.
+ *
+ * Android already worked this way regardless of the setting (see the shell's
+ * lifecycle safety), so the setting was already a lie on the platform where
+ * it mattered most.
+ */
+export type LifecycleStopReason = 'leave-page' | 'background-hidden';
+export interface DeviceLifecycleGuardOptions {
+    /** Called to stop output. Must be idempotent — the guard may fire more than once. */
+    onStop: (reason: LifecycleStopReason) => void | Promise<void>;
+}
+export declare class DeviceLifecycleGuard {
+    private readonly onStop;
+    constructor(options: DeviceLifecycleGuardOptions);
+    /** Begin watching. Returns the unsubscribe. */
+    start(): () => void;
+}
+//# sourceMappingURL=lifecycle-guard.d.ts.map

package/dist/lifecycle-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-guard.d.ts","sourceRoot":"","sources":["../src/lifecycle-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAErE,MAAM,WAAW,2BAA2B;IAC1C,qFAAqF;IACrF,MAAM,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,qBAAa,oBAAoB;IAI/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;gBAEnD,OAAO,EAAE,2BAA2B;IAIhD,+CAA+C;IAC/C,KAAK,IAAI,MAAM,IAAI;CAgCpB"}

package/dist/lifecycle-guard.js

@@ -0,0 +1,59 @@
+/**
+ * Stops device output when the page goes away or into the background.
+ *
+ * There used to be two of these — DG-Agent's `BrowserSafetyGuard` and
+ * DG-Voice's `CallSafetyGuard`, near-identical down to the in-flight guard
+ * and the listener set. They differed in exactly one way: Agent made
+ * "keep running while backgrounded" a user setting, Voice always stopped.
+ *
+ * This keeps Voice's behavior, for everyone. Screen off or tab away means
+ * stop, unconditionally, and there is no option to turn that off — which is
+ * also why the two can now be one class without the earlier worry that a
+ * wrong default would quietly ship "keeps firing while backgrounded" to a
+ * module whose author never chose it.
+ *
+ * Android already worked this way regardless of the setting (see the shell's
+ * lifecycle safety), so the setting was already a lie on the platform where
+ * it mattered most.
+ */
+export class DeviceLifecycleGuard {
+    // Not a constructor parameter property: `erasableSyntaxOnly` is on in Chat
+    // and the Android shell, and that syntax fails their build with TS1294
+    // while typecheck stays green.
+    onStop;
+    constructor(options) {
+        this.onStop = options.onStop;
+    }
+    /** Begin watching. Returns the unsubscribe. */
+    start() {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return () => undefined;
+        }
+        // One stop at a time: pagehide and visibilitychange both fire when a tab
+        // is closed, and a second stop landing mid-flight would race the first.
+        let inFlight = null;
+        const stop = (reason) => {
+            if (inFlight)
+                return;
+            inFlight = Promise.resolve(this.onStop(reason)).finally(() => {
+                inFlight = null;
+            });
+        };
+        const onLeave = () => stop('leave-page');
+        const onVisibility = () => {
+            if (document.visibilityState === 'hidden')
+                stop('background-hidden');
+        };
+        // Both leave events: pagehide is the reliable one on mobile Safari, and
+        // beforeunload is what fires on desktop closes.
+        window.addEventListener('pagehide', onLeave);
+        window.addEventListener('beforeunload', onLeave);
+        document.addEventListener('visibilitychange', onVisibility);
+        return () => {
+            window.removeEventListener('pagehide', onLeave);
+            window.removeEventListener('beforeunload', onLeave);
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
+    }
+}
+//# sourceMappingURL=lifecycle-guard.js.map

package/dist/lifecycle-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-guard.js","sourceRoot":"","sources":["../src/lifecycle-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,MAAM,OAAO,oBAAoB;IAC/B,2EAA2E;IAC3E,uEAAuE;IACvE,+BAA+B;IACd,MAAM,CAAwC;IAE/D,YAAY,OAAoC;QAC9C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,+CAA+C;IAC/C,KAAK;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;YACrE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QACzB,CAAC;QAED,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,QAAQ,GAAyB,IAAI,CAAC;QAC1C,MAAM,IAAI,GAAG,CAAC,MAA2B,EAAE,EAAE;YAC3C,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC3D,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzC,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,IAAI,QAAQ,CAAC,eAAe,KAAK,QAAQ;gBAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACvE,CAAC,CAAC;QAEF,wEAAwE;QACxE,gDAAgD;QAChD,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QACjD,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;QAE5D,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,CAAC,mBAAmB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;YACpD,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;QACjE,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/policy-engine.d.ts

@@ -0,0 +1,45 @@
+import type { ActionContext, PolicyDecision } from './contracts.js';
+import type { DeviceCommand, DeviceState, OpossumCommand } from '@dg-kit/core';
+import type { OpossumState } from '@dg-kit/protocol';
+export interface EvaluatePolicyInput {
+    context: ActionContext;
+    command: DeviceCommand;
+    deviceState: DeviceState;
+}
+export interface PolicyRule {
+    name: string;
+    evaluate(input: EvaluatePolicyInput): PolicyDecision | null;
+}
+export declare class PolicyEngine {
+    private readonly rules;
+    constructor(rules: PolicyRule[]);
+    evaluate(input: EvaluatePolicyInput): PolicyDecision;
+}
+export type OpossumPolicyDecision = {
+    type: 'allow';
+} | {
+    type: 'deny';
+    reason: string;
+} | {
+    type: 'clamp';
+    command: OpossumCommand;
+    reason: string;
+} | {
+    type: 'require-confirm';
+    reason: string;
+};
+export interface EvaluateOpossumPolicyInput {
+    context: ActionContext;
+    command: OpossumCommand;
+    deviceState: OpossumState;
+}
+export interface OpossumPolicyRule {
+    name: string;
+    evaluate(input: EvaluateOpossumPolicyInput): OpossumPolicyDecision | null;
+}
+export declare class OpossumPolicyEngine {
+    private readonly rules;
+    constructor(rules: OpossumPolicyRule[]);
+    evaluate(input: EvaluateOpossumPolicyInput): OpossumPolicyDecision;
+}
+//# sourceMappingURL=policy-engine.d.ts.map

package/dist/policy-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../src/policy-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAAC;CAC7D;AAED,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,UAAU,EAAE;IAEhD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc;CAUrD;AAcD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,YAAY,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,GAAG,IAAI,CAAC;CAC3E;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,iBAAiB,EAAE;IAEvD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB;CAUnE"}

package/dist/policy-engine.js

@@ -0,0 +1,31 @@
+export class PolicyEngine {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    evaluate(input) {
+        for (const rule of this.rules) {
+            const result = rule.evaluate(input);
+            if (result) {
+                return result;
+            }
+        }
+        return { type: 'allow' };
+    }
+}
+export class OpossumPolicyEngine {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    evaluate(input) {
+        for (const rule of this.rules) {
+            const result = rule.evaluate(input);
+            if (result) {
+                return result;
+            }
+        }
+        return { type: 'allow' };
+    }
+}
+//# sourceMappingURL=policy-engine.js.map

package/dist/policy-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.js","sourceRoot":"","sources":["../src/policy-engine.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,KAAmB;QAAnB,UAAK,GAAL,KAAK,CAAc;IAAG,CAAC;IAEpD,QAAQ,CAAC,KAA0B;QACjC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF;AA+BD,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,KAA0B;QAA1B,UAAK,GAAL,KAAK,CAAqB;IAAG,CAAC;IAE3D,QAAQ,CAAC,KAAiC;QACxC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/safety-acceptance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Acceptance state of the safety notice.
+ *
+ * One copy for the whole system. Before the merge, Agent and Chat each gated
+ * their own entry point and tracked their own state, so inside the unified
+ * shell the same notice had to be accepted twice. The notice itself now
+ * exists once (see `safety-notice-content.ts`), so its acceptance state must
+ * too — confirmed once on entering the app, counted for all modules.
+ *
+ * The gate itself is not weakened: the default is "show", and only an
+ * explicit "do not show again" checkbox is remembered. Without the checkbox
+ * the acceptance lasts for the session and the notice shows again next
+ * launch.
+ */
+/**
+ * Whether the user has permanently accepted.
+ *
+ * Returns false when storage is unreadable — it MUST be false. In private
+ * browsing or on a storage error, showing the notice one extra time is fine;
+ * silently waving the user through because a read failed is not.
+ */
+export declare function isSafetyNoticeAccepted(): boolean;
+/** Persist "do not show again". Call only on an explicit user checkbox. */
+export declare function rememberSafetyNoticeAccepted(): void;
+/** Re-arm the notice (the "show safety notice again" setting). */
+export declare function forgetSafetyNoticeAccepted(): void;
+//# sourceMappingURL=safety-acceptance.d.ts.map

package/dist/safety-acceptance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-acceptance.d.ts","sourceRoot":"","sources":["../src/safety-acceptance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAchD;AAED,2EAA2E;AAC3E,wBAAgB,4BAA4B,IAAI,IAAI,CAOnD;AAED,kEAAkE;AAClE,wBAAgB,0BAA0B,IAAI,IAAI,CAOjD"}

package/dist/safety-acceptance.js

@@ -0,0 +1,64 @@
+/**
+ * Acceptance state of the safety notice.
+ *
+ * One copy for the whole system. Before the merge, Agent and Chat each gated
+ * their own entry point and tracked their own state, so inside the unified
+ * shell the same notice had to be accepted twice. The notice itself now
+ * exists once (see `safety-notice-content.ts`), so its acceptance state must
+ * too — confirmed once on entering the app, counted for all modules.
+ *
+ * The gate itself is not weakened: the default is "show", and only an
+ * explicit "do not show again" checkbox is remembered. Without the checkbox
+ * the acceptance lasts for the session and the notice shows again next
+ * launch.
+ */
+const KEY = '0xnullai.safety-accepted';
+/** Per-module keys from before the merge, migrated once on read. */
+const LEGACY_KEYS = ['dg-chat-safety-accepted'];
+/**
+ * Whether the user has permanently accepted.
+ *
+ * Returns false when storage is unreadable — it MUST be false. In private
+ * browsing or on a storage error, showing the notice one extra time is fine;
+ * silently waving the user through because a read failed is not.
+ */
+export function isSafetyNoticeAccepted() {
+    if (typeof localStorage === 'undefined')
+        return false;
+    try {
+        if (localStorage.getItem(KEY) === 'true')
+            return true;
+        for (const legacy of LEGACY_KEYS) {
+            if (localStorage.getItem(legacy) === 'true') {
+                localStorage.setItem(KEY, 'true');
+                return true;
+            }
+        }
+    }
+    catch {
+        // Unreadable storage counts as not accepted.
+    }
+    return false;
+}
+/** Persist "do not show again". Call only on an explicit user checkbox. */
+export function rememberSafetyNoticeAccepted() {
+    try {
+        localStorage.setItem(KEY, 'true');
+    }
+    catch {
+        // If the write fails, the notice shows again next time — failing in
+        // this direction is safe.
+    }
+}
+/** Re-arm the notice (the "show safety notice again" setting). */
+export function forgetSafetyNoticeAccepted() {
+    try {
+        localStorage.removeItem(KEY);
+        for (const legacy of LEGACY_KEYS)
+            localStorage.removeItem(legacy);
+    }
+    catch {
+        // Ignore: if this fails the user can still clear site data.
+    }
+}
+//# sourceMappingURL=safety-acceptance.js.map

package/dist/safety-acceptance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-acceptance.js","sourceRoot":"","sources":["../src/safety-acceptance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,GAAG,GAAG,0BAA0B,CAAC;AACvC,oEAAoE;AACpE,MAAM,WAAW,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,CAAC;QACH,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACtD,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;gBAC5C,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAClC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,4BAA4B;IAC1C,IAAI,CAAC;QACH,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,0BAA0B;IAC5B,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,0BAA0B;IACxC,IAAI,CAAC;QACH,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC7B,KAAK,MAAM,MAAM,IAAI,WAAW;YAAE,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC"}

package/dist/safety-bus.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Safety bus: keeps "stop" reachable regardless of UI state.
+ *
+ * Each module registers its own emergency-stop function here, so the shell
+ * (or any orchestration layer) can stop *every* registered device session in
+ * one place, without knowing which modules exist or how each implements its
+ * stop.
+ *
+ * Why it exists: a module that is switched away from gets hidden (it stays
+ * mounted so BLE doesn't drop), which means its own stop button is
+ * unreachable while its device is *still outputting*. The shell needs a stop
+ * anchor that doesn't come and go with module visibility.
+ *
+ * Three design constraints:
+ * 1. `stopAll` must be best-effort — it must NOT abort because one session
+ *    throws. When one module's BLE is already gone and throws, the other
+ *    modules' devices are still outputting.
+ * 2. The registry is a Map, not an array: on hot reload / remount a module
+ *    overwrites its entry by id instead of piling up stale closures —
+ *    otherwise stopAll would invoke functions of unmounted modules.
+ * 3. No "remember who was outputting last" optimization. Stop is a
+ *    low-frequency, high-stakes operation; stopping a few idle devices is
+ *    fine, missing one because of a state-tracking bug is not.
+ */
+/**
+ * Summary of one connected device, for the shell's device bar.
+ *
+ * Lives on the safety bus rather than in a separate registry: the device bar
+ * and the stop button are two faces of the same thing — listing devices tells
+ * the user what is on their body, and stop must sit right next to that. Two
+ * registries could disagree, and the moment they disagree is exactly the
+ * dangerous one.
+ */
+export interface DeviceSummary {
+    /** Stable and unique within one module. */
+    id: string;
+    /** Device kind: coyote / opossum / paw-prints / civet-edging. */
+    kind: string;
+    /** User-facing name, usually the BLE advertised name. */
+    name: string;
+    connected: boolean;
+    /** Battery percentage; omitted when unknown. */
+    battery?: number;
+    /** Whether it is currently outputting. Visual emphasis only — NOT used to decide whether the stop button shows. */
+    active?: boolean;
+    /** Per-channel strength, for the live readout on the device bar. */
+    channels?: {
+        label: string;
+        value: number;
+        max: number;
+    }[];
+}
+export interface SafetySession {
+    /** Module id, used for overwrite-on-register and diagnostics. */
+    id: string;
+    /** User-facing name, appears in prompts like "outputting: Agent". */
+    label: string;
+    /**
+     * Whether this module currently *holds a connected device*. Note: not
+     * "whether it is outputting".
+     *
+     * Tying the stop anchor's visibility to "is outputting" makes it depend on
+     * a state chain that can break at any time (missed subscription update,
+     * lease just revoked while the device is still running). One wrong link and
+     * the button disappears at exactly the moment it is needed most. Better to
+     * long-show a button that may stop an idle device.
+     */
+    isActive: () => boolean;
+    /** Zero all device output of this module. Must be idempotent — may be called repeatedly. */
+    stop: () => void | Promise<void>;
+    /** Devices this module currently holds. The shell renders the device bar from it. */
+    devices?: () => DeviceSummary[];
+    /**
+     * Open this module's unified device picker. When present, the shell renders
+     * the one connect entry in its top device strip; modules must not duplicate
+     * the same action inside their content while mounted in the shell.
+     */
+    connect?: () => void | Promise<unknown>;
+    /** Disconnect one device listed by `devices()`. Used by the shell's top strip. */
+    disconnect?: (deviceId: string) => void | Promise<unknown>;
+    /**
+     * Called when the module loses the device lease.
+     *
+     * It MUST do three things: stop output, clear any "held down" aggregate
+     * state, and reject subsequent commands. Doing only the first is not
+     * enough — e.g. Chat's fire aggregation snapshots a baseline on the
+     * empty-to-nonempty edge; if revocation lands while someone is holding
+     * fire, the matching release message never arrives and strength stays at
+     * baseline+boost instead of falling back.
+     *
+     * It must NEVER be implemented as disconnect(). Agent and Voice clients
+     * run with autoReconnect; surrendering control by disconnecting lets the
+     * background module silently reconnect inside the GATT-disconnect event
+     * and steal the device back (the client still caches the BluetoothDevice
+     * reference, so reconnecting needs no user gesture) — while the new holder
+     * believes it has exclusive control.
+     */
+    onRevoke?: () => void | Promise<void>;
+}
+export interface StopAllResult {
+    /** Number of sessions a stop was attempted for. */
+    attempted: number;
+    /** Sessions that threw, with the error. The rest are stopped. */
+    failed: {
+        id: string;
+        error: unknown;
+    }[];
+}
+/** Register a module's device session. Returns an unregister function. */
+export declare function registerSafetySession(session: SafetySession): () => void;
+/** A registered module session, including its optional shell connect action. */
+export declare function safetySessionById(id: string | null): SafetySession | null;
+/** Modules that currently have an active device session. */
+export declare function activeSafetySessions(): SafetySession[];
+export declare function hasActiveSafetySession(): boolean;
+/**
+ * All devices currently held, grouped by module.
+ *
+ * If a module's check throws, skip that module instead of aborting — one
+ * module's broken state read must not blank the whole device bar, which
+ * would also hide the stop button next to it.
+ */
+export declare function allConnectedDevices(): {
+    sessionId: string;
+    label: string;
+    devices: DeviceSummary[];
+}[];
+/**
+ * Stop every registered session.
+ *
+ * allSettled, not all: one module throwing must not abort the others' stops
+ * — that is exactly the dangerous case (one device throws on a dropped
+ * connection while another keeps outputting).
+ */
+export declare function stopAllSafetySessions(): Promise<StopAllResult>;
+/**
+ * Hand the device lease to a module. All other modules lose control
+ * immediately and are told to stop.
+ *
+ * Revocation is best-effort: one module's onRevoke throwing must not abort
+ * the others' revocation — that is exactly the dangerous case (one module
+ * errors while another is still being remotely controlled).
+ */
+export declare function grantDeviceLease(moduleId: string | null): Promise<void>;
+/**
+ * Whether this module currently holds the device lease.
+ *
+ * Modules check this before *every* device command, not just to disable
+ * buttons — remote commands (other room members, AI) never pass through the
+ * UI.
+ */
+export declare function hasDeviceLease(moduleId: string): boolean;
+export declare function currentDeviceLease(): string | null;
+/** Subscribe to registry changes (module mount/unmount, lease transfer). */
+export declare function subscribeSafetySessions(listener: () => void): () => void;
+//# sourceMappingURL=safety-bus.d.ts.map

package/dist/safety-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-bus.d.ts","sourceRoot":"","sources":["../src/safety-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5D;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,aAAa,EAAE,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,kFAAkF;IAClF,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC1C;AAmBD,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI,CAWxE;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAEzE;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,IAAI,aAAa,EAAE,CAUtD;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B,EAAE,CAWF;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,aAAa,CAAC,CAcpE;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGxE"}

package/dist/safety-bus.js

@@ -0,0 +1,169 @@
+/**
+ * Safety bus: keeps "stop" reachable regardless of UI state.
+ *
+ * Each module registers its own emergency-stop function here, so the shell
+ * (or any orchestration layer) can stop *every* registered device session in
+ * one place, without knowing which modules exist or how each implements its
+ * stop.
+ *
+ * Why it exists: a module that is switched away from gets hidden (it stays
+ * mounted so BLE doesn't drop), which means its own stop button is
+ * unreachable while its device is *still outputting*. The shell needs a stop
+ * anchor that doesn't come and go with module visibility.
+ *
+ * Three design constraints:
+ * 1. `stopAll` must be best-effort — it must NOT abort because one session
+ *    throws. When one module's BLE is already gone and throws, the other
+ *    modules' devices are still outputting.
+ * 2. The registry is a Map, not an array: on hot reload / remount a module
+ *    overwrites its entry by id instead of piling up stale closures —
+ *    otherwise stopAll would invoke functions of unmounted modules.
+ * 3. No "remember who was outputting last" optimization. Stop is a
+ *    low-frequency, high-stakes operation; stopping a few idle devices is
+ *    fine, missing one because of a state-tracking bug is not.
+ */
+const sessions = new Map();
+const listeners = new Set();
+/**
+ * The module currently holding the device lease.
+ *
+ * `null` means no module holds it — e.g. while sitting on the home screen.
+ * Then *no module may issue commands*, but devices stay connected and the
+ * stop button stays usable. This matters: surrendering control is not the
+ * same as disconnecting.
+ */
+let leaseHolder = null;
+function notify() {
+    for (const l of listeners)
+        l();
+}
+/** Register a module's device session. Returns an unregister function. */
+export function registerSafetySession(session) {
+    sessions.set(session.id, session);
+    notify();
+    return () => {
+        // Delete only while still ours: after a remount the new session has
+        // overwritten the old one, and the old cleanup must not remove the new.
+        if (sessions.get(session.id) === session) {
+            sessions.delete(session.id);
+            notify();
+        }
+    };
+}
+/** A registered module session, including its optional shell connect action. */
+export function safetySessionById(id) {
+    return id ? (sessions.get(id) ?? null) : null;
+}
+/** Modules that currently have an active device session. */
+export function activeSafetySessions() {
+    return [...sessions.values()].filter((s) => {
+        try {
+            return s.isActive();
+        }
+        catch {
+            // If the check itself throws, treat as active — better to show one
+            // extra stop button than to miss one.
+            return true;
+        }
+    });
+}
+export function hasActiveSafetySession() {
+    return activeSafetySessions().length > 0;
+}
+/**
+ * All devices currently held, grouped by module.
+ *
+ * If a module's check throws, skip that module instead of aborting — one
+ * module's broken state read must not blank the whole device bar, which
+ * would also hide the stop button next to it.
+ */
+export function allConnectedDevices() {
+    const out = [];
+    for (const s of sessions.values()) {
+        try {
+            const devices = s.devices?.().filter((d) => d.connected) ?? [];
+            if (devices.length)
+                out.push({ sessionId: s.id, label: s.label, devices });
+        }
+        catch {
+            // Skip this one; the rest proceed as normal.
+        }
+    }
+    return out;
+}
+/**
+ * Stop every registered session.
+ *
+ * allSettled, not all: one module throwing must not abort the others' stops
+ * — that is exactly the dangerous case (one device throws on a dropped
+ * connection while another keeps outputting).
+ */
+export async function stopAllSafetySessions() {
+    const list = [...sessions.values()];
+    const results = await Promise.allSettled(
+    // The wrapper is required: if stop() throws *synchronously*, the
+    // exception escapes inside map and never reaches allSettled — exactly
+    // the dangerous case (one device throws on disconnect, none of the
+    // others get stopped). The unit test "one session throwing must not
+    // abort the others" guards this.
+    list.map((s) => Promise.resolve().then(() => s.stop())));
+    const failed = results.flatMap((r, i) => r.status === 'rejected' ? [{ id: list[i].id, error: r.reason }] : []);
+    return { attempted: list.length, failed };
+}
+/**
+ * Hand the device lease to a module. All other modules lose control
+ * immediately and are told to stop.
+ *
+ * Revocation is best-effort: one module's onRevoke throwing must not abort
+ * the others' revocation — that is exactly the dangerous case (one module
+ * errors while another is still being remotely controlled).
+ */
+export async function grantDeviceLease(moduleId) {
+    if (leaseHolder === moduleId)
+        return;
+    const previous = leaseHolder;
+    leaseHolder = moduleId;
+    notify();
+    if (!previous)
+        return;
+    const losing = sessions.get(previous);
+    if (!losing?.onRevoke)
+        return;
+    try {
+        // `try { await f() }` already catches a synchronous throw — the call
+        // itself is inside the try. (stopAllSafetySessions needs the extra
+        // wrapper because its call happens inside `map`, outside allSettled —
+        // a different situation.)
+        await losing.onRevoke();
+    }
+    catch {
+        // If revocation fails, at least stop it — it no longer holds the lease,
+        // but its device may still be outputting.
+        try {
+            await losing.stop();
+        }
+        catch {
+            // Both paths failed: the global stop button is still reachable; that
+            // is the last line of defense.
+        }
+    }
+}
+/**
+ * Whether this module currently holds the device lease.
+ *
+ * Modules check this before *every* device command, not just to disable
+ * buttons — remote commands (other room members, AI) never pass through the
+ * UI.
+ */
+export function hasDeviceLease(moduleId) {
+    return leaseHolder === moduleId;
+}
+export function currentDeviceLease() {
+    return leaseHolder;
+}
+/** Subscribe to registry changes (module mount/unmount, lease transfer). */
+export function subscribeSafetySessions(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+//# sourceMappingURL=safety-bus.js.map