@dg-kit/safety 1.14.0

package/README.md

@@ -0,0 +1,16 @@
+# @dg-kit/safety
+
+The shared device safety chain for DG-Lab integrations. It provides strength and burst policy
+enforcement, cold-start clamps, serialized command execution, emergency-stop preemption, device
+leases, lifecycle guards, and the cross-module safety bus used by 0xNuller.
+
+## Install
+
+```bash
+npm install @dg-kit/safety
+```
+
+Safety policy is enforced before commands reach a transport. Applications should still expose a
+clear stop control and should not treat account identity as permission to control a device.
+
+The package is ESM-only and exports its public API from the package root.

package/dist/contracts.d.ts

@@ -0,0 +1,44 @@
+import type { DeviceCommand } from '@dg-kit/core';
+/** Command origin. Used for policy/permission decisions and for routing replies back to the original channel. */
+export type SourceType = 'web' | 'qq' | 'telegram' | 'cli' | 'api' | 'system' | 'sensor';
+export interface ActionContext {
+    sessionId: string;
+    sourceType: SourceType;
+    sourceUserId?: string;
+    sourceUserName?: string;
+    sourceChannelId?: string;
+    traceId: string;
+}
+export type PermissionDecision = {
+    type: 'approve-once';
+} | {
+    type: 'approve-scoped';
+    expiresAt?: number;
+} | {
+    type: 'deny';
+    reason?: string;
+};
+export type PolicyDecision = {
+    type: 'allow';
+} | {
+    type: 'deny';
+    reason: string;
+} | {
+    type: 'clamp';
+    command: DeviceCommand;
+    reason: string;
+} | {
+    type: 'require-confirm';
+    reason: string;
+};
+export interface PermissionRequest {
+    context: ActionContext;
+    toolName: string;
+    toolDisplayName?: string;
+    summary: string;
+    args: Record<string, unknown>;
+}
+export interface PermissionService {
+    request(input: PermissionRequest): Promise<PermissionDecision>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,iHAAiH;AACjH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,IAAI,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzF,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,MAAM,cAAc,GACtB;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,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChE"}

package/dist/contracts.js

@@ -0,0 +1,9 @@
+// Safety-chain contracts.
+//
+// Before the merge these types existed twice: in @dg-agent/core and in
+// apps/voice/src/lib/types.ts (whose file header described itself as a
+// "mirror slice" of the former). They describe how a caller drives the
+// safety chain, not the BLE protocol itself — hence this package rather
+// than @dg-kit/core.
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,qBAAqB"}

package/dist/default-policies.d.ts

@@ -0,0 +1,36 @@
+import type { OpossumPolicyRule } from './policy-engine.js';
+import type { PolicyRule } from './policy-engine.js';
+export declare const DEFAULT_MAX_COLD_START_STRENGTH = 10;
+export declare const DEFAULT_MAX_ADJUST_STEP = 10;
+export declare const DEFAULT_MAX_BURST_DURATION_MS = 5000;
+export declare const DEFAULT_MAX_OPOSSUM_COLD_START_INTENSITY = 10;
+export declare const DEFAULT_MAX_OPOSSUM_ADJUST_STEP = 10;
+export declare const DEFAULT_USER_MAX_OPOSSUM_INTENSITY = 50;
+export interface DefaultPolicyOptions {
+    maxStrengthA?: number;
+    maxStrengthB?: number;
+    maxColdStartStrength?: number;
+    maxAdjustStep?: number;
+    maxBurstDurationMs?: number;
+    maxBurstStrengthAbsolute?: number;
+    maxBurstStrengthRelative?: number;
+}
+export declare function createDefaultPolicyRules(options?: DefaultPolicyOptions): PolicyRule[];
+export interface DefaultOpossumPolicyOptions {
+    maxColdStartIntensity?: number;
+    maxAdjustStep?: number;
+    /** User absolute intensity cap per channel — mirrors Coyote's maxStrengthA/B. */
+    maxIntensityA?: number;
+    maxIntensityB?: number;
+}
+/**
+ * Mirrors `createDefaultPolicyRules` in spirit: require-connection first,
+ * then a cold-start intensity clamp, then a step-adjust clamp, then a
+ * permission gate. Deliberately narrower than Coyote's rule set — no
+ * per-channel hardware limit (Opossum has no `limitA`/`limitB` concept).
+ * `vibrateBurst` shares the same per-channel intensity ceiling as
+ * `vibrateStart` rather than growing Coyote-style burst-specific
+ * absolute/relative caps.
+ */
+export declare function createDefaultOpossumPolicyRules(options?: DefaultOpossumPolicyOptions): OpossumPolicyRule[];
+//# sourceMappingURL=default-policies.d.ts.map

package/dist/default-policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-policies.d.ts","sourceRoot":"","sources":["../src/default-policies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAQnD,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAG5B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAMD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,EAAE,CA6JzF;AA8CD,MAAM,WAAW,2BAA2B;IAC1C,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,2BAAgC,GACxC,iBAAiB,EAAE,CAwGrB"}

package/dist/default-policies.js

@@ -0,0 +1,333 @@
+export const DEFAULT_MAX_COLD_START_STRENGTH = 10;
+export const DEFAULT_MAX_ADJUST_STEP = 10;
+export const DEFAULT_MAX_BURST_DURATION_MS = 5_000;
+const MAX_ADJUST_STEP_LIMIT = 200;
+const MAX_BURST_DURATION_LIMIT_MS = 20_000;
+const DEFAULT_USER_MAX_STRENGTH = 50;
+// Opossum intensity is also a 0-200 range (see OpossumCommand doc comment in
+// @dg-kit/core), so its safety caps default to the same magnitude as
+// Coyote's cold-start / step-adjust caps rather than inventing new numbers.
+export const DEFAULT_MAX_OPOSSUM_COLD_START_INTENSITY = 10;
+export const DEFAULT_MAX_OPOSSUM_ADJUST_STEP = 10;
+// Absolute per-channel ceiling, mirroring Coyote's DEFAULT_USER_MAX_STRENGTH.
+export const DEFAULT_USER_MAX_OPOSSUM_INTENSITY = 50;
+function requiresConfirmation(command) {
+    return command.type !== 'stop' && command.type !== 'emergencyStop';
+}
+export function createDefaultPolicyRules(options = {}) {
+    const maxStrengthA = normalizeStrengthLimit(options.maxStrengthA);
+    const maxStrengthB = normalizeStrengthLimit(options.maxStrengthB);
+    const maxColdStartStrength = normalizeColdStartStrengthLimit(options.maxColdStartStrength);
+    const maxAdjustStep = normalizeAdjustStepLimit(options.maxAdjustStep);
+    const maxBurstDurationMs = normalizeBurstDurationLimit(options.maxBurstDurationMs);
+    const maxBurstStrengthAbsolute = normalizeOptionalCap(options.maxBurstStrengthAbsolute);
+    const maxBurstStrengthRelative = normalizeOptionalCap(options.maxBurstStrengthRelative);
+    return [
+        {
+            name: 'require-device-connection',
+            evaluate({ deviceState }) {
+                if (!deviceState.connected) {
+                    return { type: 'deny', reason: '设备未连接' };
+                }
+                return null;
+            },
+        },
+        {
+            name: 'soft-start',
+            evaluate({ command, deviceState }) {
+                if (command.type !== 'start')
+                    return null;
+                const current = command.channel === 'A' ? deviceState.strengthA : deviceState.strengthB;
+                if (current > 0)
+                    return null;
+                if (command.strength <= maxColdStartStrength)
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: { ...command, strength: maxColdStartStrength },
+                    reason: `冷启动强度上限为 ${maxColdStartStrength}`,
+                };
+            },
+        },
+        {
+            name: 'user-strength-cap',
+            evaluate({ command, deviceState }) {
+                switch (command.type) {
+                    case 'start': {
+                        const effectiveLimit = getEffectiveLimit(command.channel, deviceState, {
+                            A: maxStrengthA,
+                            B: maxStrengthB,
+                        });
+                        if (command.strength <= effectiveLimit)
+                            return null;
+                        return {
+                            type: 'clamp',
+                            command: { ...command, strength: effectiveLimit },
+                            reason: `${command.channel} 通道强度上限为 ${effectiveLimit}`,
+                        };
+                    }
+                    case 'burst': {
+                        const effectiveLimit = getEffectiveLimit(command.channel, deviceState, {
+                            A: maxStrengthA,
+                            B: maxStrengthB,
+                        });
+                        if (command.strength <= effectiveLimit)
+                            return null;
+                        return {
+                            type: 'clamp',
+                            command: { ...command, strength: effectiveLimit },
+                            reason: `${command.channel} 通道 burst 强度上限为 ${effectiveLimit}`,
+                        };
+                    }
+                    case 'adjustStrength': {
+                        const current = command.channel === 'A' ? deviceState.strengthA : deviceState.strengthB;
+                        const effectiveLimit = getEffectiveLimit(command.channel, deviceState, {
+                            A: maxStrengthA,
+                            B: maxStrengthB,
+                        });
+                        const target = clamp(current + command.delta, 0, effectiveLimit);
+                        const clampedDelta = target - current;
+                        if (clampedDelta === command.delta)
+                            return null;
+                        return {
+                            type: 'clamp',
+                            command: { ...command, delta: clampedDelta },
+                            reason: `调整后的强度需遵守 ${command.channel} 通道上限 ${effectiveLimit}`,
+                        };
+                    }
+                    default:
+                        return null;
+                }
+            },
+        },
+        {
+            name: 'burst-strength-cap',
+            evaluate({ command, deviceState }) {
+                if (command.type !== 'burst')
+                    return null;
+                if (maxBurstStrengthAbsolute === 0 && maxBurstStrengthRelative === 0)
+                    return null;
+                const current = command.channel === 'A' ? deviceState.strengthA : deviceState.strengthB;
+                let cap = Number.POSITIVE_INFINITY;
+                const reasons = [];
+                if (maxBurstStrengthAbsolute > 0 && command.strength > maxBurstStrengthAbsolute) {
+                    cap = Math.min(cap, maxBurstStrengthAbsolute);
+                    reasons.push(`突增绝对强度上限 ${maxBurstStrengthAbsolute}`);
+                }
+                if (maxBurstStrengthRelative > 0) {
+                    const relativeCap = current + maxBurstStrengthRelative;
+                    if (command.strength > relativeCap) {
+                        cap = Math.min(cap, relativeCap);
+                        reasons.push(`突增相对强度上限 +${maxBurstStrengthRelative}（当前 ${current} → 不超过 ${relativeCap}）`);
+                    }
+                }
+                if (!Number.isFinite(cap))
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: { ...command, strength: cap },
+                    reason: reasons.join('；'),
+                };
+            },
+        },
+        {
+            name: 'step-adjust',
+            evaluate({ command }) {
+                if (command.type !== 'adjustStrength')
+                    return null;
+                if (Math.abs(command.delta) <= maxAdjustStep)
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: {
+                        ...command,
+                        delta: Math.sign(command.delta || 1) * maxAdjustStep,
+                    },
+                    reason: `单次调节幅度上限为 ±${maxAdjustStep}`,
+                };
+            },
+        },
+        {
+            name: 'burst-duration',
+            evaluate({ command }) {
+                if (command.type !== 'burst')
+                    return null;
+                if (command.durationMs <= maxBurstDurationMs)
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: {
+                        ...command,
+                        durationMs: maxBurstDurationMs,
+                    },
+                    reason: `Burst 时长上限为 ${maxBurstDurationMs}ms`,
+                };
+            },
+        },
+        {
+            name: 'permission-gate',
+            evaluate({ command }) {
+                if (!requiresConfirmation(command))
+                    return null;
+                return {
+                    type: 'require-confirm',
+                    reason: '该操作会修改设备状态，需要先获取权限',
+                };
+            },
+        },
+    ];
+}
+function normalizeStrengthLimit(value) {
+    const raw = typeof value === 'number' ? value : DEFAULT_USER_MAX_STRENGTH;
+    return clamp(raw, 0, 200);
+}
+function normalizeColdStartStrengthLimit(value) {
+    const raw = typeof value === 'number' ? value : DEFAULT_MAX_COLD_START_STRENGTH;
+    return clamp(raw, 0, 200);
+}
+function normalizeAdjustStepLimit(value) {
+    const raw = typeof value === 'number' ? value : DEFAULT_MAX_ADJUST_STEP;
+    return clamp(raw, 1, MAX_ADJUST_STEP_LIMIT);
+}
+function normalizeBurstDurationLimit(value) {
+    const raw = typeof value === 'number' ? value : DEFAULT_MAX_BURST_DURATION_MS;
+    return clamp(raw, 100, MAX_BURST_DURATION_LIMIT_MS);
+}
+// 0 means "disabled" for the burst-specific caps. Negative input is
+// coerced to 0 so a misconfigured slider can't widen the cap into the
+// negative-strength territory.
+function normalizeOptionalCap(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.min(Math.round(value), 200);
+}
+function getEffectiveLimit(channel, deviceState, userLimits) {
+    const hardware = channel === 'A' ? deviceState.limitA : deviceState.limitB;
+    const user = userLimits[channel];
+    return Math.min(hardware, user);
+}
+function clamp(value, min, max) {
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        return min;
+    return Math.max(min, Math.min(max, Math.round(number)));
+}
+function opossumRequiresConfirmation(command) {
+    return command.type !== 'vibrateStop';
+}
+/**
+ * Mirrors `createDefaultPolicyRules` in spirit: require-connection first,
+ * then a cold-start intensity clamp, then a step-adjust clamp, then a
+ * permission gate. Deliberately narrower than Coyote's rule set — no
+ * per-channel hardware limit (Opossum has no `limitA`/`limitB` concept).
+ * `vibrateBurst` shares the same per-channel intensity ceiling as
+ * `vibrateStart` rather than growing Coyote-style burst-specific
+ * absolute/relative caps.
+ */
+export function createDefaultOpossumPolicyRules(options = {}) {
+    const maxColdStartIntensity = normalizeOpossumIntensityLimit(options.maxColdStartIntensity, DEFAULT_MAX_OPOSSUM_COLD_START_INTENSITY);
+    const maxAdjustStep = normalizeOpossumAdjustStepLimit(options.maxAdjustStep);
+    const maxIntensityA = normalizeOpossumIntensityLimit(options.maxIntensityA, DEFAULT_USER_MAX_OPOSSUM_INTENSITY);
+    const maxIntensityB = normalizeOpossumIntensityLimit(options.maxIntensityB, DEFAULT_USER_MAX_OPOSSUM_INTENSITY);
+    return [
+        {
+            name: 'require-opossum-connection',
+            evaluate({ deviceState }) {
+                if (!deviceState.connected) {
+                    return { type: 'deny', reason: '设备未连接' };
+                }
+                return null;
+            },
+        },
+        {
+            name: 'opossum-cold-start',
+            evaluate({ command, deviceState }) {
+                if (command.type !== 'vibrateStart')
+                    return null;
+                const current = command.channel === 'A' ? deviceState.intensityA : deviceState.intensityB;
+                if (current > 0)
+                    return null;
+                if (command.intensity <= maxColdStartIntensity)
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: { ...command, intensity: maxColdStartIntensity },
+                    reason: `负鼠冷启动强度上限为 ${maxColdStartIntensity}`,
+                };
+            },
+        },
+        {
+            // Mirrors Coyote's 'user-strength-cap': an absolute per-channel
+            // ceiling the AI can never exceed regardless of how many small
+            // vibrate_adjust steps it stacks up. Without this, cold-start +
+            // step-adjust alone bound each individual call but not the
+            // accumulated total — the AI could still walk intensity up to the
+            // protocol max (200) one step at a time.
+            name: 'opossum-user-intensity-cap',
+            evaluate({ command, deviceState }) {
+                if (command.type === 'vibrateSetPattern')
+                    return null;
+                const effectiveLimit = command.channel === 'A' ? maxIntensityA : maxIntensityB;
+                if (command.type === 'vibrateStart' || command.type === 'vibrateBurst') {
+                    if (command.intensity <= effectiveLimit)
+                        return null;
+                    return {
+                        type: 'clamp',
+                        command: { ...command, intensity: effectiveLimit },
+                        reason: `负鼠 ${command.channel} 通道强度上限为 ${effectiveLimit}`,
+                    };
+                }
+                if (command.type === 'vibrateAdjust') {
+                    const current = command.channel === 'A' ? deviceState.intensityA : deviceState.intensityB;
+                    const target = clamp(current + command.delta, 0, effectiveLimit);
+                    const clampedDelta = target - current;
+                    if (clampedDelta === command.delta)
+                        return null;
+                    return {
+                        type: 'clamp',
+                        command: { ...command, delta: clampedDelta },
+                        reason: `调整后的强度需遵守负鼠 ${command.channel} 通道上限 ${effectiveLimit}`,
+                    };
+                }
+                return null;
+            },
+        },
+        {
+            name: 'opossum-step-adjust',
+            evaluate({ command }) {
+                if (command.type !== 'vibrateAdjust')
+                    return null;
+                if (Math.abs(command.delta) <= maxAdjustStep)
+                    return null;
+                return {
+                    type: 'clamp',
+                    command: {
+                        ...command,
+                        delta: Math.sign(command.delta || 1) * maxAdjustStep,
+                    },
+                    reason: `负鼠单次调节幅度上限为 ±${maxAdjustStep}`,
+                };
+            },
+        },
+        {
+            name: 'opossum-permission-gate',
+            evaluate({ command }) {
+                if (!opossumRequiresConfirmation(command))
+                    return null;
+                return {
+                    type: 'require-confirm',
+                    reason: '该操作会修改设备状态，需要先获取权限',
+                };
+            },
+        },
+    ];
+}
+function normalizeOpossumIntensityLimit(value, fallback) {
+    const raw = typeof value === 'number' ? value : fallback;
+    return clamp(raw, 0, 200);
+}
+function normalizeOpossumAdjustStepLimit(value) {
+    const raw = typeof value === 'number' ? value : DEFAULT_MAX_OPOSSUM_ADJUST_STEP;
+    return clamp(raw, 1, MAX_ADJUST_STEP_LIMIT);
+}
+//# sourceMappingURL=default-policies.js.map

package/dist/default-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-policies.js","sourceRoot":"","sources":["../src/default-policies.ts"],"names":[],"mappings":"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"}

package/dist/device-command-queue.d.ts

@@ -0,0 +1,60 @@
+import type { DeviceClient, OpossumCommand } from '@dg-kit/core';
+import type { DeviceCommand, DeviceCommandResult } from '@dg-kit/core';
+import type { OpossumClient, OpossumCommandResult } from '@dg-kit/protocol';
+export interface PriorityInterrupt<TCommand, TResult> {
+    /** Which command(s) should bypass the queue and run immediately. */
+    matches(command: TCommand): boolean;
+    /** How to actually run a matched command (typically not via `execute()`). */
+    run(command: TCommand): Promise<TResult>;
+    /** Result for a task that was already queued when a later interrupt fired. */
+    skippedResult(): Promise<TResult>;
+}
+export interface SerialCommandQueueOptions<TCommand, TResult> {
+    execute(command: TCommand): Promise<TResult>;
+    /** Omit for a plain FIFO queue with no priority-interrupt concept. */
+    priorityInterrupt?: PriorityInterrupt<TCommand, TResult>;
+}
+/**
+ * Runs commands against a device one at a time, so concurrent tool calls
+ * can't race each other's writes — a rejected command doesn't jam the
+ * queue, the next enqueued command still runs.
+ *
+ * An optional `priorityInterrupt` lets one command "type" (Coyote's
+ * `emergencyStop`) skip the line entirely: it bumps a generation counter
+ * and runs immediately via `run()` rather than `execute()`, and any
+ * already-queued-but-not-yet-run task notices its generation is stale and
+ * resolves with `skippedResult()` instead of actually executing. Extracted
+ * from `DeviceCommandQueue` (which needs the interrupt) and reused as a
+ * plain FIFO by `OpossumCommandQueue` (which doesn't — see its own doc
+ * comment for why).
+ */
+export declare class SerialCommandQueue<TCommand, TResult> {
+    private readonly options;
+    private tail;
+    private generation;
+    constructor(options: SerialCommandQueueOptions<TCommand, TResult>);
+    enqueue(command: TCommand): Promise<TResult>;
+}
+export declare class DeviceCommandQueue {
+    private readonly device;
+    private readonly queue;
+    constructor(device: DeviceClient);
+    enqueue(command: DeviceCommand): Promise<DeviceCommandResult>;
+}
+/**
+ * Serializes Opossum vibration commands the same way `DeviceCommandQueue`
+ * serializes Coyote commands, so concurrent `vibrate_*` tool calls can't
+ * race each other's writes. No `emergencyStop`-style generation bump is
+ * needed here: Opossum has no command analogous to Coyote's `emergencyStop`
+ * variant in its own command union (`vibrate_stop` already exists for that),
+ * and the runtime-wide panic button calls `OpossumClient.emergencyStop()`
+ * directly (see `AgentRuntime.emergencyStop`), bypassing the queue exactly
+ * like Coyote's does.
+ */
+export declare class OpossumCommandQueue {
+    private readonly device;
+    private readonly queue;
+    constructor(device: OpossumClient);
+    enqueue(command: OpossumCommand): Promise<OpossumCommandResult>;
+}
+//# sourceMappingURL=device-command-queue.d.ts.map

package/dist/device-command-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-command-queue.d.ts","sourceRoot":"","sources":["../src/device-command-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE5E,MAAM,WAAW,iBAAiB,CAAC,QAAQ,EAAE,OAAO;IAClD,oEAAoE;IACpE,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IACpC,6EAA6E;IAC7E,GAAG,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,8EAA8E;IAC9E,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB,CAAC,QAAQ,EAAE,OAAO;IAC1D,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAkB,CAAC,QAAQ,EAAE,OAAO;IAInC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,UAAU,CAAK;gBAEM,OAAO,EAAE,yBAAyB,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE5E,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;CA0CnD;AAED,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyD;gBAElD,MAAM,EAAE,YAAY;IAoB3C,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAGpE;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAmB;IAGlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2D;gBAEpD,MAAM,EAAE,aAAa;IAM5C,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAGtE"}

package/dist/device-command-queue.js

@@ -0,0 +1,105 @@
+/**
+ * Runs commands against a device one at a time, so concurrent tool calls
+ * can't race each other's writes — a rejected command doesn't jam the
+ * queue, the next enqueued command still runs.
+ *
+ * An optional `priorityInterrupt` lets one command "type" (Coyote's
+ * `emergencyStop`) skip the line entirely: it bumps a generation counter
+ * and runs immediately via `run()` rather than `execute()`, and any
+ * already-queued-but-not-yet-run task notices its generation is stale and
+ * resolves with `skippedResult()` instead of actually executing. Extracted
+ * from `DeviceCommandQueue` (which needs the interrupt) and reused as a
+ * plain FIFO by `OpossumCommandQueue` (which doesn't — see its own doc
+ * comment for why).
+ */
+export class SerialCommandQueue {
+    options;
+    tail = Promise.resolve();
+    generation = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async enqueue(command) {
+        const interrupt = this.options.priorityInterrupt;
+        if (interrupt?.matches(command)) {
+            this.generation += 1;
+            return interrupt.run(command);
+        }
+        const generation = this.generation;
+        const task = this.tail.then(async () => {
+            if (interrupt && generation !== this.generation) {
+                return interrupt.skippedResult();
+            }
+            const startedAt = this.generation;
+            const result = await this.options.execute(command);
+            // An emergency stop happened *while the command was executing*: it was
+            // already in flight, so the generation check can't catch it — the check
+            // runs before execute, and the stop runs concurrently. Its write lands
+            // after the stop, so the device halts and then jumps back to the
+            // previous strength. Observed exactly in that order (stop → in-flight
+            // +10 lands → strength 10).
+            //
+            // A packet already sent cannot be recalled; what we can do is stop
+            // again right after. Emergency stop must be idempotent, so a duplicate
+            // stop is safe — a missed one is not.
+            if (interrupt && startedAt !== this.generation) {
+                await interrupt.run(command);
+                return interrupt.skippedResult();
+            }
+            return result;
+        });
+        this.tail = task.then(() => undefined, () => undefined);
+        return task;
+    }
+}
+export class DeviceCommandQueue {
+    device;
+    queue;
+    constructor(device) {
+        this.device = device;
+        this.queue = new SerialCommandQueue({
+            execute: (command) => this.device.execute(command),
+            priorityInterrupt: {
+                matches: (command) => command.type === 'emergencyStop',
+                run: async () => {
+                    await this.device.emergencyStop();
+                    return {
+                        state: await this.device.getState(),
+                        notes: ['queue-drained-by-emergency-stop'],
+                    };
+                },
+                skippedResult: async () => ({
+                    state: await this.device.getState(),
+                    notes: ['skipped-after-priority-interrupt'],
+                }),
+            },
+        });
+    }
+    async enqueue(command) {
+        return this.queue.enqueue(command);
+    }
+}
+/**
+ * Serializes Opossum vibration commands the same way `DeviceCommandQueue`
+ * serializes Coyote commands, so concurrent `vibrate_*` tool calls can't
+ * race each other's writes. No `emergencyStop`-style generation bump is
+ * needed here: Opossum has no command analogous to Coyote's `emergencyStop`
+ * variant in its own command union (`vibrate_stop` already exists for that),
+ * and the runtime-wide panic button calls `OpossumClient.emergencyStop()`
+ * directly (see `AgentRuntime.emergencyStop`), bypassing the queue exactly
+ * like Coyote's does.
+ */
+export class OpossumCommandQueue {
+    device;
+    queue;
+    constructor(device) {
+        this.device = device;
+        this.queue = new SerialCommandQueue({
+            execute: (command) => this.device.execute(command),
+        });
+    }
+    async enqueue(command) {
+        return this.queue.enqueue(command);
+    }
+}
+//# sourceMappingURL=device-command-queue.js.map

package/dist/device-command-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-command-queue.js","sourceRoot":"","sources":["../src/device-command-queue.ts"],"names":[],"mappings":"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"}