@flowdot.ai/guardian-agent 0.1.0

package/dist/estop/heartbeat.js

@@ -0,0 +1,135 @@
+/**
+ * Dead-man's-switch heartbeat. SPEC §6 (v0.4.0+).
+ *
+ * For long-running surfaces (CLI daemon, MCP server's persistent session,
+ * Native main loop) the agent (or its harness) must call
+ * `monitor.heartbeat()` every N seconds. If no heartbeat arrives within
+ * `softMs`, an `x_heartbeat_warning` audit row is written (no behavior
+ * change). If still no heartbeat by `hardMs`, the configured `EStopLocal`
+ * is pressed with `reason: 'heartbeat_missed'`.
+ *
+ * Pure mechanism: setInterval + timestamp arithmetic. The supervisor does
+ * not decide whether the agent should be alive — only whether it is
+ * claiming to be.
+ *
+ * OPT-IN PER SURFACE. Default OFF. A surface that hasn't wired
+ * `heartbeat()` calls into its main loop must not enable this — that's a
+ * day-1 false E-stop.
+ */
+/**
+ * State machine: idle → softMissed → hardMissed. Each transition writes
+ * an audit row (warning for softMissed, estop_press for hardMissed). The
+ * monitor stops checking once hardMissed fires; restart by constructing a
+ * new monitor (a new session).
+ */
+export class HeartbeatMonitor {
+    audit;
+    estop;
+    softMs;
+    hardMs;
+    checkIntervalMs;
+    now;
+    setIntervalFn;
+    clearIntervalFn;
+    lastBeat;
+    state = 'idle';
+    interval = null;
+    stopped = false;
+    constructor(options) {
+        if (options.softMs <= 0)
+            throw new Error('softMs must be > 0');
+        if (options.hardMs <= options.softMs) {
+            throw new Error('hardMs must be > softMs');
+        }
+        this.audit = options.audit;
+        this.estop = options.estop;
+        this.softMs = options.softMs;
+        this.hardMs = options.hardMs;
+        this.now = options.now ?? Date.now;
+        this.setIntervalFn =
+            options.setIntervalFn ?? ((cb, ms) => setInterval(cb, ms));
+        this.clearIntervalFn =
+            options.clearIntervalFn ?? ((h) => clearInterval(h));
+        this.checkIntervalMs =
+            options.checkIntervalMs ?? Math.max(50, Math.min(5000, Math.floor(this.softMs / 4)));
+        this.lastBeat = this.now();
+    }
+    /** Start the watchdog. Idempotent. */
+    start() {
+        if (this.interval !== null || this.stopped)
+            return;
+        this.lastBeat = this.now();
+        this.interval = this.setIntervalFn(() => {
+            void this.tick();
+        }, this.checkIntervalMs);
+    }
+    /** Stop the watchdog. Idempotent. Call from supervisor close(). */
+    stop() {
+        this.stopped = true;
+        if (this.interval !== null) {
+            this.clearIntervalFn(this.interval);
+            this.interval = null;
+        }
+    }
+    /**
+     * Record a heartbeat. Resets the state machine to `idle` if a soft
+     * warning had fired but no hard miss yet.
+     */
+    heartbeat() {
+        if (this.state === 'hardMissed') {
+            // Cannot recover from a hard miss. Caller should restart the session.
+            return;
+        }
+        this.lastBeat = this.now();
+        this.state = 'idle';
+    }
+    /** Current state (for tests + introspection). */
+    getState() {
+        return { state: this.state, lastBeatMs: this.lastBeat };
+    }
+    /**
+     * Public tick. Called automatically by the interval; exposed so tests can
+     * drive deterministically without real timers.
+     */
+    async tick() {
+        if (this.stopped)
+            return;
+        const elapsed = this.now() - this.lastBeat;
+        if (elapsed >= this.hardMs && this.state !== 'hardMissed') {
+            this.state = 'hardMissed';
+            if (this.audit) {
+                // Audit the miss explicitly even though estop.press will also write
+                // an estop_press row. The two are useful together: the warning
+                // captures the elapsed time + threshold, the estop_press carries
+                // the eventual halt.
+                await this.audit.append({
+                    kind: 'x_heartbeat_warning',
+                    status: 'halted',
+                    initiator: 'system',
+                    detail: { elapsed_ms: elapsed, hard_ms: this.hardMs, level: 'hard' },
+                });
+            }
+            if (this.estop) {
+                await this.estop.press({
+                    reason: 'heartbeat_missed',
+                    initiator: 'system',
+                });
+            }
+            // Once hard-missed, stop checking — the session is halted.
+            this.stop();
+            return;
+        }
+        if (elapsed >= this.softMs && this.state === 'idle') {
+            this.state = 'softMissed';
+            if (this.audit) {
+                await this.audit.append({
+                    kind: 'x_heartbeat_warning',
+                    status: 'approved',
+                    initiator: 'system',
+                    detail: { elapsed_ms: elapsed, soft_ms: this.softMs, level: 'soft' },
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/estop/heartbeat.js.map

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

package/dist/estop/hub.d.ts

@@ -0,0 +1,76 @@
+/**
+ * EStopHub — hub-coordinated emergency-stop adapter. SPEC §5.4.
+ *
+ * Pluggable state store (in-memory by default; FlowDot supplies a SQL adapter).
+ * Per-user scoping. 1-second cache TTL on isPressed reads (matches FlowDot).
+ * Notifier fan-out on every press AND clear.
+ */
+import type { AuditLogWriter } from '../audit/writer.js';
+import type { Notifier } from '../notify/types.js';
+import type { EStopClearOptions, EStopClearResult, EStopPressOptions, EStopPressResult, EStopState } from './types.js';
+/**
+ * Backing store for hub state. Implementations: in-memory (default),
+ * SQL-backed (host-supplied).
+ */
+export interface EStopStateStore {
+    get(userId: string): Promise<EStopState | null>;
+    set(userId: string, state: EStopState): Promise<void>;
+}
+/**
+ * Channel that fans out press notifications to live daemons (push side).
+ * Library-internal; FlowDot supplies the `comms_daemon_commands` adapter.
+ */
+export interface EStopBroadcastChannel {
+    broadcastPress(userId: string, state: EStopState): Promise<void>;
+    broadcastClear(userId: string, state: EStopState): Promise<void>;
+}
+export interface EStopHubOptions {
+    state: EStopStateStore;
+    audit: AuditLogWriter;
+    notifier?: Notifier;
+    broadcast?: EStopBroadcastChannel;
+    /** Cache TTL for isPressed in ms. SPEC §5.4 default = 1000. */
+    cacheTtlMs?: number;
+    /**
+     * Required recent-auth check for clear() — host supplies it. Return true if
+     * the operator has confirmed authentication recently; false to force a
+     * second factor (password.confirm flow on the host).
+     */
+    recentAuthCheck?: (userId: string, options: EStopClearOptions) => Promise<boolean>;
+    /** Canonical clear URL included in notifications. */
+    canonicalClearUrl?: string;
+}
+/** Source surface tag included in audit + notification. */
+export interface EStopActorContext {
+    source: string;
+    ip?: string;
+    userAgent?: string;
+}
+export declare class EStopHub {
+    private readonly state;
+    private readonly audit;
+    private readonly notifier;
+    private readonly broadcast;
+    private readonly cacheTtlMs;
+    private readonly recentAuthCheck;
+    private readonly canonicalClearUrl;
+    private cache;
+    constructor(options: EStopHubOptions);
+    /** Cached, hot-path check used by the middleware. */
+    isPressed(userId: string): Promise<boolean>;
+    status(userId: string): Promise<EStopState>;
+    press(userId: string, options: EStopPressOptions, actor?: EStopActorContext): Promise<EStopPressResult>;
+    clear(userId: string, options: EStopClearOptions, actor?: EStopActorContext): Promise<EStopClearResult>;
+    /** Force-invalidate a single user's cache entry. Idempotent. */
+    invalidateCache(userId: string): void;
+    /** Clear the entire cache. Useful for tests + Redis-down scenarios. */
+    invalidateAllCache(): void;
+    private fireNotification;
+}
+/** Reference in-memory state store. */
+export declare class InMemoryEStopStateStore implements EStopStateStore {
+    private states;
+    get(userId: string): Promise<EStopState | null>;
+    set(userId: string, state: EStopState): Promise<void>;
+}
+//# sourceMappingURL=hub.d.ts.map

package/dist/estop/hub.d.ts.map

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

package/dist/estop/hub.js

@@ -0,0 +1,167 @@
+/**
+ * EStopHub — hub-coordinated emergency-stop adapter. SPEC §5.4.
+ *
+ * Pluggable state store (in-memory by default; FlowDot supplies a SQL adapter).
+ * Per-user scoping. 1-second cache TTL on isPressed reads (matches FlowDot).
+ * Notifier fan-out on every press AND clear.
+ */
+const DEFAULT_CACHE_TTL_MS = 1000;
+export class EStopHub {
+    state;
+    audit;
+    notifier;
+    broadcast;
+    cacheTtlMs;
+    recentAuthCheck;
+    canonicalClearUrl;
+    cache = new Map();
+    constructor(options) {
+        this.state = options.state;
+        this.audit = options.audit;
+        this.notifier = options.notifier;
+        this.broadcast = options.broadcast;
+        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.recentAuthCheck = options.recentAuthCheck;
+        this.canonicalClearUrl = options.canonicalClearUrl;
+    }
+    /** Cached, hot-path check used by the middleware. */
+    async isPressed(userId) {
+        const now = Date.now();
+        const entry = this.cache.get(userId);
+        if (entry && entry.expiresAt > now)
+            return entry.value;
+        const state = await this.state.get(userId);
+        const pressed = state?.pressed ?? false;
+        this.cache.set(userId, { value: pressed, expiresAt: now + this.cacheTtlMs });
+        return pressed;
+    }
+    async status(userId) {
+        return (await this.state.get(userId)) ?? { pressed: false };
+    }
+    async press(userId, options, actor = { source: 'hub' }) {
+        // SPEC §7: reject agent-initiated press only if deployment policy demands
+        // it. The library default allows agent-initiated press (they SHOULD be
+        // able to halt themselves on anomaly). The caller controls via initiator.
+        const initiator = options.initiator ?? 'operator';
+        const existing = (await this.state.get(userId)) ?? { pressed: false };
+        const newState = existing.pressed
+            ? existing
+            : {
+                pressed: true,
+                pressedAt: new Date().toISOString(),
+                pressedReason: options.reason,
+                ...(options.operatorId === undefined ? {} : { pressedOperatorId: options.operatorId }),
+            };
+        if (!existing.pressed) {
+            await this.state.set(userId, newState);
+            this.invalidateCache(userId);
+        }
+        await this.audit.append({
+            kind: 'estop_press',
+            status: 'halted',
+            initiator,
+            detail: {
+                user_id: userId,
+                source: actor.source,
+                reason: options.reason,
+                ...(options.operatorId === undefined ? {} : { operator_id: options.operatorId }),
+                ...(actor.ip === undefined ? {} : { ip: actor.ip }),
+                ...(actor.userAgent === undefined ? {} : { user_agent: actor.userAgent }),
+                ...(options.detail ?? {}),
+            },
+        });
+        if (this.broadcast && !existing.pressed) {
+            await this.broadcast.broadcastPress(userId, newState);
+        }
+        await this.fireNotification('estop_press', userId, actor, {
+            reason: options.reason,
+            ...(options.operatorId === undefined ? {} : { operator_id: options.operatorId }),
+            ...(options.detail ?? {}),
+        });
+        return { state: { ...newState } };
+    }
+    async clear(userId, options, actor = { source: 'hub' }) {
+        // SPEC §7: agent-initiated clear MUST be rejected.
+        const initiator = options.initiator ?? 'operator';
+        if (initiator === 'agent') {
+            return {
+                state: (await this.state.get(userId)) ?? { pressed: false },
+                authRequired: false,
+            };
+        }
+        if (this.recentAuthCheck) {
+            const ok = await this.recentAuthCheck(userId, options);
+            if (!ok) {
+                return {
+                    state: (await this.state.get(userId)) ?? { pressed: false },
+                    authRequired: true,
+                };
+            }
+        }
+        const existing = (await this.state.get(userId)) ?? { pressed: false };
+        if (!existing.pressed) {
+            return { state: existing };
+        }
+        const cleared = {
+            pressed: false,
+            clearedAt: new Date().toISOString(),
+        };
+        await this.state.set(userId, cleared);
+        this.invalidateCache(userId);
+        await this.audit.append({
+            kind: 'estop_clear',
+            status: 'approved',
+            initiator,
+            detail: {
+                user_id: userId,
+                source: actor.source,
+                ...(options.operatorId === undefined ? {} : { operator_id: options.operatorId }),
+                ...(actor.ip === undefined ? {} : { ip: actor.ip }),
+                ...(actor.userAgent === undefined ? {} : { user_agent: actor.userAgent }),
+                ...(options.detail ?? {}),
+            },
+        });
+        if (this.broadcast) {
+            await this.broadcast.broadcastClear(userId, cleared);
+        }
+        await this.fireNotification('estop_clear', userId, actor, {
+            ...(options.operatorId === undefined ? {} : { operator_id: options.operatorId }),
+            ...(options.detail ?? {}),
+        });
+        return { state: cleared };
+    }
+    /** Force-invalidate a single user's cache entry. Idempotent. */
+    invalidateCache(userId) {
+        this.cache.delete(userId);
+    }
+    /** Clear the entire cache. Useful for tests + Redis-down scenarios. */
+    invalidateAllCache() {
+        this.cache.clear();
+    }
+    async fireNotification(kind, userId, actor, summary) {
+        if (!this.notifier)
+            return;
+        await this.notifier.notify({
+            kind,
+            userId,
+            agentId: '',
+            ts: new Date().toISOString(),
+            source: actor.source,
+            summary,
+            ...(this.canonicalClearUrl === undefined
+                ? {}
+                : { canonicalClearUrl: this.canonicalClearUrl }),
+        });
+    }
+}
+/** Reference in-memory state store. */
+export class InMemoryEStopStateStore {
+    states = new Map();
+    async get(userId) {
+        return this.states.get(userId) ?? null;
+    }
+    async set(userId, state) {
+        this.states.set(userId, state);
+    }
+}
+//# sourceMappingURL=hub.js.map

package/dist/estop/hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../../src/estop/hub.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsDH,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC,MAAM,OAAO,QAAQ;IACF,KAAK,CAAkB;IACvB,KAAK,CAAiB;IACtB,QAAQ,CAAuB;IAC/B,SAAS,CAAoC;IAC7C,UAAU,CAAS;IACnB,eAAe,CAElB;IACG,iBAAiB,CAAqB;IAE/C,KAAK,GAAG,IAAI,GAAG,EAAiD,CAAC;IAEzE,YAAY,OAAwB;QAClC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,oBAAoB,CAAC;QAC7D,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IACrD,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,KAAK,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QAEvD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC7E,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc;QACzB,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,KAAK,CACT,MAAc,EACd,OAA0B,EAC1B,QAA2B,EAAE,MAAM,EAAE,KAAK,EAAE;QAE5C,0EAA0E;QAC1E,uEAAuE;QACvE,0EAA0E;QAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC;QAElD,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACtE,MAAM,QAAQ,GAAe,QAAQ,CAAC,OAAO;YAC3C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC;gBACE,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,aAAa,EAAE,OAAO,CAAC,MAAM;gBAC7B,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;aACvF,CAAC;QAEN,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACvC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,SAAS;YACT,MAAM,EAAE;gBACN,OAAO,EAAE,MAAM;gBACf,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;gBAChF,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;gBACnD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;gBACzE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;aAC1B;SACF,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACxC,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE;YACxD,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;YAChF,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;SAC1B,CAAC,CAAC;QAEH,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,EAAE,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,KAAK,CACT,MAAc,EACd,OAA0B,EAC1B,QAA2B,EAAE,MAAM,EAAE,KAAK,EAAE;QAE5C,mDAAmD;QACnD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC;QAClD,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;YAC1B,OAAO;gBACL,KAAK,EAAE,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;gBAC3D,YAAY,EAAE,KAAK;aACpB,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACvD,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,OAAO;oBACL,KAAK,EAAE,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;oBAC3D,YAAY,EAAE,IAAI;iBACnB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACtE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAED,MAAM,OAAO,GAAe;YAC1B,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAE7B,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,UAAU;YAClB,SAAS;YACT,MAAM,EAAE;gBACN,OAAO,EAAE,MAAM;gBACf,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;gBAChF,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;gBACnD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;gBACzE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;aAC1B;SACF,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE;YACxD,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;YAChF,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;SAC1B,CAAC,CAAC;QAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED,gEAAgE;IAChE,eAAe,CAAC,MAAc;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,uEAAuE;IACvE,kBAAkB;QAChB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,gBAAgB,CAC5B,IAAsB,EACtB,MAAc,EACd,KAAwB,EACxB,OAAgC;QAEhC,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YACzB,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,EAAE;YACX,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO;YACP,GAAG,CAAC,IAAI,CAAC,iBAAiB,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC;SACnD,CAAC,CAAC;IACL,CAAC;CACF;AAED,uCAAuC;AACvC,MAAM,OAAO,uBAAuB;IAC1B,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE/C,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,KAAiB;QACzC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;CACF"}

package/dist/estop/index.d.ts

@@ -0,0 +1,12 @@
+export { EStopLocal } from './local.js';
+export type { EStopLocalOptions } from './local.js';
+export { EStopHub, InMemoryEStopStateStore, } from './hub.js';
+export type { EStopHubOptions, EStopStateStore, EStopBroadcastChannel, EStopActorContext, } from './hub.js';
+export { createEStopMiddleware } from './middleware.js';
+export type { EStopMiddlewareOptions, MiddlewareRequest, MiddlewareResponse, MiddlewareNext, } from './middleware.js';
+export { createEStopPoller, EStopPoller } from './poller.js';
+export type { EStopPollerOptions } from './poller.js';
+export { HeartbeatMonitor } from './heartbeat.js';
+export type { HeartbeatMonitorOptions } from './heartbeat.js';
+export type { EStopState, EStopPressOptions, EStopClearOptions, EStopPressResult, EStopClearResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/estop/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/estop/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,QAAQ,EACR,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/estop/index.js

@@ -0,0 +1,6 @@
+export { EStopLocal } from './local.js';
+export { EStopHub, InMemoryEStopStateStore, } from './hub.js';
+export { createEStopMiddleware } from './middleware.js';
+export { createEStopPoller, EStopPoller } from './poller.js';
+export { HeartbeatMonitor } from './heartbeat.js';
+//# sourceMappingURL=index.js.map

package/dist/estop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/estop/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EACL,QAAQ,EACR,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAOlB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAOxD,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/estop/local.d.ts

@@ -0,0 +1,31 @@
+/**
+ * EStopLocal — in-process emergency-stop primitive. SPEC §5.3.
+ *
+ * Single-process deployment: halt flag is an AbortController; clear semantics
+ * are terminal (session must be reconstructed).
+ */
+import type { AuditLogWriter } from '../audit/writer.js';
+import type { Notifier } from '../notify/types.js';
+import type { EStopClearOptions, EStopClearResult, EStopPressOptions, EStopPressResult, EStopState } from './types.js';
+export interface EStopLocalOptions {
+    audit?: AuditLogWriter;
+    notifier?: Notifier;
+    /** If true, construct already-pressed. Useful for tests; rare in production. */
+    initiallyPressed?: boolean;
+}
+export declare class EStopLocal {
+    private state;
+    private controller;
+    private readonly audit;
+    private readonly notifier;
+    constructor(options?: EStopLocalOptions);
+    /** AbortSignal callers can listen on. Aborts when pressed. */
+    get abortSignal(): AbortSignal;
+    isPressed(): boolean;
+    getState(): EStopState;
+    press(options: EStopPressOptions): Promise<EStopPressResult>;
+    clear(options: EStopClearOptions): Promise<EStopClearResult>;
+    private recordEvent;
+    private fireNotification;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/estop/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/estop/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;gBAEpC,OAAO,GAAE,iBAAsB;IAgB3C,8DAA8D;IAC9D,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,SAAS,IAAI,OAAO;IAIpB,QAAQ,IAAI,UAAU;IAIhB,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqB5D,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAoBpD,WAAW;YAmBX,gBAAgB;CAiB/B"}

package/dist/estop/local.js

@@ -0,0 +1,101 @@
+/**
+ * EStopLocal — in-process emergency-stop primitive. SPEC §5.3.
+ *
+ * Single-process deployment: halt flag is an AbortController; clear semantics
+ * are terminal (session must be reconstructed).
+ */
+export class EStopLocal {
+    state;
+    controller;
+    audit;
+    notifier;
+    constructor(options = {}) {
+        this.audit = options.audit;
+        this.notifier = options.notifier;
+        this.controller = new AbortController();
+        this.state = { pressed: false };
+        if (options.initiallyPressed) {
+            this.state = {
+                pressed: true,
+                pressedAt: new Date().toISOString(),
+                pressedReason: 'initially_pressed',
+            };
+            this.controller.abort();
+        }
+    }
+    /** AbortSignal callers can listen on. Aborts when pressed. */
+    get abortSignal() {
+        return this.controller.signal;
+    }
+    isPressed() {
+        return this.state.pressed;
+    }
+    getState() {
+        return { ...this.state };
+    }
+    async press(options) {
+        if (this.state.pressed) {
+            // Idempotent: re-pressing doesn't change state but does record an audit event.
+            await this.recordEvent('estop_press', options);
+            return { state: this.getState() };
+        }
+        this.state = {
+            pressed: true,
+            pressedAt: new Date().toISOString(),
+            pressedReason: options.reason,
+            ...(options.operatorId === undefined ? {} : { pressedOperatorId: options.operatorId }),
+        };
+        this.controller.abort();
+        await this.recordEvent('estop_press', options);
+        await this.fireNotification('estop_press', options);
+        return { state: this.getState() };
+    }
+    async clear(options) {
+        if (!this.state.pressed) {
+            // No-op clear: don't audit, don't notify.
+            return { state: this.getState() };
+        }
+        this.state = {
+            pressed: false,
+            clearedAt: new Date().toISOString(),
+        };
+        // EStopLocal does NOT reset the AbortController: the existing signal stays
+        // aborted forever. Recovery requires a new EStopLocal instance.
+        await this.recordEvent('estop_clear', options);
+        await this.fireNotification('estop_clear', options);
+        return { state: this.getState() };
+    }
+    async recordEvent(kind, options) {
+        if (!this.audit)
+            return;
+        const detail = {
+            ...(options.detail ?? {}),
+        };
+        if ('reason' in options)
+            detail.reason = options.reason;
+        if (options.operatorId !== undefined)
+            detail.operator_id = options.operatorId;
+        await this.audit.append({
+            kind,
+            status: kind === 'estop_press' ? 'halted' : 'approved',
+            initiator: options.initiator ?? 'operator',
+            detail,
+        });
+    }
+    async fireNotification(kind, options) {
+        if (!this.notifier)
+            return;
+        await this.notifier.notify({
+            kind,
+            agentId: '',
+            ts: new Date().toISOString(),
+            source: 'local',
+            summary: {
+                ...(options.detail ?? {}),
+                ...('reason' in options ? { reason: options.reason } : {}),
+                ...(options.operatorId !== undefined ? { operator_id: options.operatorId } : {}),
+            },
+        });
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/estop/local.js.map

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

package/dist/estop/middleware.d.ts

@@ -0,0 +1,36 @@
+/**
+ * createEStopMiddleware — Express/Connect/Fastify-compatible middleware that
+ * returns HTTP 423 Locked when the resolved user is currently pressed.
+ * SPEC §5.4.
+ *
+ * Framework-agnostic: the middleware signature is `(req, res, next)` which
+ * Express, Connect, and Fastify (with middleware mode) all accept.
+ */
+import type { EStopHub } from './hub.js';
+/** Minimal subset of Node's IncomingMessage we read. */
+export interface MiddlewareRequest {
+    headers: Record<string, string | string[] | undefined>;
+    url?: string;
+    method?: string;
+}
+/** Minimal subset of Node's ServerResponse we write. */
+export interface MiddlewareResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+export type MiddlewareNext = (err?: unknown) => void;
+export interface EStopMiddlewareOptions {
+    /** Host extracts the user id from the request. Return null to skip the gate. */
+    resolveUserId: (req: MiddlewareRequest) => string | null;
+    /** Bypass predicate — return true to skip the gate (e.g., for /estop/clear). */
+    exclude?: (req: MiddlewareRequest) => boolean;
+    /** Override the JSON body returned on 423. */
+    lockedResponseBody?: (state: {
+        pressedAt?: string;
+    }, userId: string) => unknown;
+    /** Header name carrying the request originator (operator | agent | system). */
+    initiatorHeader?: string;
+}
+export declare function createEStopMiddleware(hub: EStopHub, options: EStopMiddlewareOptions): (req: MiddlewareRequest, res: MiddlewareResponse, next: MiddlewareNext) => Promise<void>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/estop/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/estop/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,aAAa,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,GAAG,IAAI,CAAC;IACzD,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAC9C,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAChF,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,sBAAsB,GAC9B,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAqB1F"}