@tjamescouch/agentchat 0.25.2 → 0.26.0

package/dist/lib/escalation.js

@@ -0,0 +1,286 @@
+/**
+ * Escalation Engine
+ * Progressive moderation: warn -> throttle -> timeout -> kick
+ *
+ * Tracks per-connection violation state and escalates enforcement
+ * as agents continue to exceed rate limits.
+ */
+// Escalation levels in order of severity
+export var EscalationLevel;
+(function (EscalationLevel) {
+    EscalationLevel["NONE"] = "none";
+    EscalationLevel["WARNED"] = "warned";
+    EscalationLevel["THROTTLED"] = "throttled";
+    EscalationLevel["TIMED_OUT"] = "timed_out";
+    EscalationLevel["KICKED"] = "kicked";
+})(EscalationLevel || (EscalationLevel = {}));
+const DEFAULTS = {
+    warnAfterViolations: 3,
+    throttleAfterViolations: 6,
+    timeoutAfterViolations: 10,
+    kickAfterTimeouts: 3,
+    throttleDurationMs: 5000, // 5 seconds between messages when throttled
+    timeoutDurationMs: 60000, // 1 minute timeout
+    violationWindowMs: 60000, // 1 minute violation window
+    cooldownMs: 300000, // 5 minutes clean = decay one level
+    timeoutMemoryMs: 3600000, // 1 hour: timeout history lingers even after level decay
+};
+export class EscalationEngine {
+    states = new Map();
+    options;
+    logger;
+    constructor(options = {}, logger) {
+        this.options = { ...DEFAULTS, ...options };
+        this.logger = logger || (() => { });
+    }
+    /**
+     * Record a rate limit violation and return the action to take.
+     * Called whenever a connection exceeds the rate limit.
+     */
+    recordViolation(connectionId, agentId) {
+        const now = Date.now();
+        let state = this.states.get(connectionId);
+        if (!state) {
+            state = this._createState(now);
+            this.states.set(connectionId, state);
+        }
+        // Apply gradual decay based on time since last violation.
+        // Each cooldown period of inactivity drops one escalation level.
+        this._applyDecay(state, now);
+        // Reset violation count if the violation window has expired
+        if (now - state.windowStart > this.options.violationWindowMs) {
+            state.violations = 0;
+            state.windowStart = now;
+        }
+        state.violations++;
+        state.lastViolationAt = now;
+        const meta = { connectionId, agentId, violations: state.violations, level: state.level };
+        // Check if currently timed out
+        if (state.level === EscalationLevel.TIMED_OUT && now < state.timeoutUntil) {
+            return {
+                type: 'timeout',
+                message: `You are timed out. Try again in ${Math.ceil((state.timeoutUntil - now) / 1000)} seconds.`,
+                timeoutMs: state.timeoutUntil - now,
+            };
+        }
+        // Determine escalation based on violation count
+        if (state.violations >= this.options.timeoutAfterViolations) {
+            state.timeoutCount++;
+            if (state.timeoutCount >= this.options.kickAfterTimeouts) {
+                state.level = EscalationLevel.KICKED;
+                this.logger('escalation_kick', { ...meta, timeoutCount: state.timeoutCount });
+                return {
+                    type: 'kick',
+                    message: `Kicked for repeated violations (${state.timeoutCount} timeouts). Please moderate your message rate.`,
+                };
+            }
+            state.level = EscalationLevel.TIMED_OUT;
+            state.timeoutUntil = now + this.options.timeoutDurationMs;
+            state.violations = 0; // reset violations for next window
+            state.windowStart = now;
+            this.logger('escalation_timeout', { ...meta, timeoutCount: state.timeoutCount, durationMs: this.options.timeoutDurationMs });
+            return {
+                type: 'timeout',
+                message: `Timed out for ${Math.ceil(this.options.timeoutDurationMs / 1000)} seconds due to excessive messaging. (Timeout ${state.timeoutCount}/${this.options.kickAfterTimeouts})`,
+                timeoutMs: this.options.timeoutDurationMs,
+            };
+        }
+        if (state.violations >= this.options.throttleAfterViolations) {
+            state.level = EscalationLevel.THROTTLED;
+            state.throttleUntil = now + this.options.throttleDurationMs;
+            this.logger('escalation_throttle', { ...meta, throttleMs: this.options.throttleDurationMs });
+            return {
+                type: 'throttle',
+                message: `Throttled: your messages are being rate-limited to 1 per ${Math.ceil(this.options.throttleDurationMs / 1000)} seconds.`,
+                throttleMs: this.options.throttleDurationMs,
+            };
+        }
+        if (state.violations >= this.options.warnAfterViolations) {
+            state.warningsSent++;
+            if (state.level === EscalationLevel.NONE) {
+                state.level = EscalationLevel.WARNED;
+            }
+            this.logger('escalation_warn', { ...meta, warningsSent: state.warningsSent });
+            return {
+                type: 'warn',
+                message: `Warning: you are sending messages too quickly. Continued violations will result in throttling. (${state.violations}/${this.options.throttleAfterViolations} before throttle)`,
+            };
+        }
+        // Below warning threshold — just silently rate limit
+        return {
+            type: 'allow',
+            message: '',
+        };
+    }
+    /**
+     * Check if a connection is currently throttled and should have messages delayed.
+     * Returns the additional delay in ms, or 0 if not throttled.
+     */
+    getThrottleDelay(connectionId) {
+        const state = this.states.get(connectionId);
+        if (!state)
+            return 0;
+        // Apply gradual decay first
+        this._applyDecay(state, Date.now());
+        if (state.level === EscalationLevel.THROTTLED) {
+            return this.options.throttleDurationMs;
+        }
+        return 0;
+    }
+    /**
+     * Check if a connection is currently timed out.
+     * Returns true if the connection should be rejected.
+     */
+    isTimedOut(connectionId) {
+        const state = this.states.get(connectionId);
+        if (!state)
+            return false;
+        const now = Date.now();
+        // Apply gradual decay first
+        this._applyDecay(state, now);
+        if (state.level === EscalationLevel.TIMED_OUT && now < state.timeoutUntil) {
+            return true;
+        }
+        // Timeout expired — move back to throttled level
+        if (state.level === EscalationLevel.TIMED_OUT && now >= state.timeoutUntil) {
+            state.level = EscalationLevel.THROTTLED;
+        }
+        return false;
+    }
+    /**
+     * Get the current escalation level for a connection.
+     */
+    getLevel(connectionId) {
+        const state = this.states.get(connectionId);
+        if (!state)
+            return EscalationLevel.NONE;
+        // Apply gradual decay
+        this._applyDecay(state, Date.now());
+        return state.level;
+    }
+    /**
+     * Get the full state for a connection (for debugging/logging).
+     */
+    getState(connectionId) {
+        return this.states.get(connectionId);
+    }
+    /**
+     * Remove tracking for a disconnected connection.
+     */
+    remove(connectionId) {
+        this.states.delete(connectionId);
+    }
+    /**
+     * Reset a connection's escalation state (e.g., after admin intervention).
+     */
+    reset(connectionId) {
+        this.states.delete(connectionId);
+    }
+    /**
+     * Clean up stale entries (connections that have been clean for a while).
+     * Call periodically to prevent memory leaks.
+     */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [id, state] of this.states) {
+            // Apply decay first
+            this._applyDecay(state, now);
+            // Only remove if fully decayed to NONE AND timeout memory has expired
+            if (state.level === EscalationLevel.NONE && now - state.lastViolationAt > this.options.timeoutMemoryMs) {
+                this.states.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get stats for monitoring.
+     */
+    stats() {
+        let warned = 0;
+        let throttled = 0;
+        let timedOut = 0;
+        for (const state of this.states.values()) {
+            switch (state.level) {
+                case EscalationLevel.WARNED:
+                    warned++;
+                    break;
+                case EscalationLevel.THROTTLED:
+                    throttled++;
+                    break;
+                case EscalationLevel.TIMED_OUT:
+                    timedOut++;
+                    break;
+            }
+        }
+        return {
+            tracked: this.states.size,
+            warned,
+            throttled,
+            timedOut,
+        };
+    }
+    /**
+     * Gradual decay: drop one escalation level per cooldown period of inactivity.
+     * KICKED → TIMED_OUT → THROTTLED → WARNED → NONE
+     */
+    _applyDecay(state, now) {
+        if (state.lastViolationAt === 0)
+            return; // no violations yet
+        const elapsed = now - state.lastViolationAt;
+        if (elapsed < this.options.cooldownMs)
+            return; // not enough time
+        const levelsToDrop = Math.floor(elapsed / this.options.cooldownMs);
+        const ladder = [
+            EscalationLevel.NONE,
+            EscalationLevel.WARNED,
+            EscalationLevel.THROTTLED,
+            EscalationLevel.TIMED_OUT,
+            EscalationLevel.KICKED,
+        ];
+        const currentIdx = ladder.indexOf(state.level);
+        if (currentIdx <= 0)
+            return; // already at NONE
+        const newIdx = Math.max(0, currentIdx - levelsToDrop);
+        const oldLevel = state.level;
+        state.level = ladder[newIdx];
+        // If we decayed past TIMED_OUT, clear timeout state
+        if (newIdx < ladder.indexOf(EscalationLevel.TIMED_OUT)) {
+            state.timeoutUntil = 0;
+        }
+        // Reset violations when decaying (fresh window)
+        if (newIdx !== currentIdx) {
+            state.violations = 0;
+            state.windowStart = now;
+            if (newIdx === 0) {
+                // Level fully decayed to NONE — reset warnings
+                state.warningsSent = 0;
+                // timeoutCount has its own longer TTL to prevent patient attacker gaming
+                if (elapsed >= this.options.timeoutMemoryMs) {
+                    state.timeoutCount = 0;
+                }
+            }
+            this.logger('escalation_decay', {
+                connectionId: 'unknown', // caller doesn't pass this, but it's just for logging
+                from: oldLevel,
+                to: state.level,
+                levelsToDrop,
+                elapsedMs: elapsed,
+            });
+        }
+    }
+    _createState(now) {
+        return {
+            level: EscalationLevel.NONE,
+            violations: 0,
+            warningsSent: 0,
+            throttleUntil: 0,
+            timeoutUntil: 0,
+            timeoutCount: 0,
+            lastViolationAt: 0,
+            windowStart: now,
+        };
+    }
+}
+//# sourceMappingURL=escalation.js.map

package/dist/lib/escalation.js.map

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

package/dist/lib/escalation.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for EscalationEngine
+ * Progressive moderation: warn -> throttle -> timeout -> kick
+ *
+ * Run with: npx tsx lib/escalation.test.ts
+ */
+export {};
+//# sourceMappingURL=escalation.test.d.ts.map

package/dist/lib/escalation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.test.d.ts","sourceRoot":"","sources":["../../lib/escalation.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/lib/escalation.test.js

@@ -0,0 +1,348 @@
+/**
+ * Tests for EscalationEngine
+ * Progressive moderation: warn -> throttle -> timeout -> kick
+ *
+ * Run with: npx tsx lib/escalation.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { EscalationEngine, EscalationLevel } from './escalation.js';
+describe('EscalationEngine', () => {
+    function makeEngine() {
+        return new EscalationEngine({
+            warnAfterViolations: 3,
+            throttleAfterViolations: 6,
+            timeoutAfterViolations: 10,
+            kickAfterTimeouts: 3,
+            throttleDurationMs: 5000,
+            timeoutDurationMs: 60000,
+            violationWindowMs: 60000,
+            cooldownMs: 300000,
+        });
+    }
+    describe('basic escalation ladder', () => {
+        it('allows first few violations silently', () => {
+            const engine = makeEngine();
+            const r1 = engine.recordViolation('conn1');
+            const r2 = engine.recordViolation('conn1');
+            assert.equal(r1.type, 'allow');
+            assert.equal(r2.type, 'allow');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+        });
+        it('warns after threshold violations', () => {
+            const engine = makeEngine();
+            engine.recordViolation('conn1');
+            engine.recordViolation('conn1');
+            const r3 = engine.recordViolation('conn1');
+            assert.equal(r3.type, 'warn');
+            assert.ok(r3.message.includes('Warning'));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.WARNED);
+        });
+        it('throttles after more violations', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 5; i++)
+                engine.recordViolation('conn1');
+            const r6 = engine.recordViolation('conn1');
+            assert.equal(r6.type, 'throttle');
+            assert.equal(r6.throttleMs, 5000);
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+        });
+        it('times out after continued violations', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 9; i++)
+                engine.recordViolation('conn1');
+            const r10 = engine.recordViolation('conn1');
+            assert.equal(r10.type, 'timeout');
+            assert.equal(r10.timeoutMs, 60000);
+            assert.ok(r10.message.includes('Timed out'));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.TIMED_OUT);
+        });
+        it('kicks after repeated timeouts', async () => {
+            // Use a very short timeout so we can wait it out
+            const engine = new EscalationEngine({
+                warnAfterViolations: 3,
+                throttleAfterViolations: 6,
+                timeoutAfterViolations: 10,
+                kickAfterTimeouts: 3,
+                throttleDurationMs: 5000,
+                timeoutDurationMs: 50, // 50ms timeout
+                violationWindowMs: 60000,
+                cooldownMs: 300000,
+            });
+            let lastAction;
+            for (let round = 0; round < 3; round++) {
+                for (let i = 0; i < 10; i++) {
+                    lastAction = engine.recordViolation('conn1');
+                }
+                // Wait for the timeout to expire before next round
+                if (round < 2) {
+                    await new Promise(r => setTimeout(r, 60));
+                }
+            }
+            assert.equal(lastAction.type, 'kick');
+            const state = engine.getState('conn1');
+            assert.equal(state.level, EscalationLevel.KICKED);
+        });
+    });
+    describe('timeout behavior', () => {
+        it('reports timed out when checking during timeout period', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 10; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.isTimedOut('conn1'), true);
+        });
+        it('returns false for non-existent connections', () => {
+            const engine = makeEngine();
+            assert.equal(engine.isTimedOut('nonexistent'), false);
+        });
+    });
+    describe('throttle delay', () => {
+        it('returns 0 for untracked connections', () => {
+            const engine = makeEngine();
+            assert.equal(engine.getThrottleDelay('unknown'), 0);
+        });
+        it('returns throttle duration when throttled', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getThrottleDelay('conn1'), 5000);
+        });
+        it('returns 0 when not yet throttled', () => {
+            const engine = makeEngine();
+            engine.recordViolation('conn1');
+            assert.equal(engine.getThrottleDelay('conn1'), 0);
+        });
+    });
+    describe('isolation between connections', () => {
+        it('tracks connections independently', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 3; i++)
+                engine.recordViolation('conn1');
+            engine.recordViolation('conn2');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.WARNED);
+            assert.equal(engine.getLevel('conn2'), EscalationLevel.NONE);
+        });
+    });
+    describe('cleanup and removal', () => {
+        it('removes connection state', () => {
+            const engine = makeEngine();
+            engine.recordViolation('conn1');
+            engine.remove('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+        });
+        it('resets connection state', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+            engine.reset('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+        });
+    });
+    describe('stats', () => {
+        it('reports correct counts', () => {
+            const engine = makeEngine();
+            for (let i = 0; i < 3; i++)
+                engine.recordViolation('conn1');
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn2');
+            for (let i = 0; i < 10; i++)
+                engine.recordViolation('conn3');
+            const stats = engine.stats();
+            assert.equal(stats.tracked, 3);
+            assert.equal(stats.warned, 1);
+            assert.equal(stats.throttled, 1);
+            assert.equal(stats.timedOut, 1);
+        });
+    });
+    describe('logging', () => {
+        it('calls logger on escalation events', () => {
+            const logs = [];
+            const engine = new EscalationEngine({ warnAfterViolations: 2 }, (event, data) => logs.push({ event, data }));
+            engine.recordViolation('conn1');
+            engine.recordViolation('conn1');
+            assert.equal(logs.length, 1);
+            assert.equal(logs[0].event, 'escalation_warn');
+        });
+    });
+    describe('gradual decay', () => {
+        it('decays one level per cooldown period', async () => {
+            // Use very short cooldown so we can actually wait it out
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                timeoutAfterViolations: 6,
+                kickAfterTimeouts: 3,
+                throttleDurationMs: 5000,
+                timeoutDurationMs: 30, // very short so timeout expires quickly
+                violationWindowMs: 60000,
+                cooldownMs: 50, // 50ms cooldown
+            });
+            // Escalate to THROTTLED
+            for (let i = 0; i < 4; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+            // Wait one cooldown period — should decay to WARNED
+            await new Promise(r => setTimeout(r, 60));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.WARNED);
+            // Wait another cooldown period — should decay to NONE
+            await new Promise(r => setTimeout(r, 60));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+        });
+        it('decays multiple levels when enough time passes', async () => {
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                timeoutAfterViolations: 6,
+                kickAfterTimeouts: 3,
+                throttleDurationMs: 5000,
+                timeoutDurationMs: 30,
+                violationWindowMs: 60000,
+                cooldownMs: 50,
+            });
+            // Escalate to THROTTLED (level 2)
+            for (let i = 0; i < 4; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+            // Wait 2 cooldown periods — should decay straight to NONE
+            await new Promise(r => setTimeout(r, 120));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+        });
+        it('does not decay during active violations', () => {
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                cooldownMs: 50,
+            });
+            // Rapid violations — no time for decay
+            for (let i = 0; i < 4; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+        });
+        it('re-escalates after partial decay', async () => {
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                cooldownMs: 50,
+                violationWindowMs: 200,
+            });
+            // Escalate to THROTTLED
+            for (let i = 0; i < 4; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+            // Wait for decay to WARNED
+            await new Promise(r => setTimeout(r, 60));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.WARNED);
+            // New violations should re-escalate
+            for (let i = 0; i < 4; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.THROTTLED);
+        });
+        it('timeoutCount survives level decay (patient attacker defense)', async () => {
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                timeoutAfterViolations: 6,
+                kickAfterTimeouts: 2,
+                throttleDurationMs: 5000,
+                timeoutDurationMs: 30, // very short timeout
+                violationWindowMs: 200,
+                cooldownMs: 50, // fast decay
+                timeoutMemoryMs: 500, // timeout history lasts 500ms (much longer than cooldown)
+            });
+            // Round 1: escalate to timeout
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.TIMED_OUT);
+            const state1 = engine.getState('conn1');
+            assert.equal(state1.timeoutCount, 1);
+            // Wait for timeout to expire + full level decay to NONE
+            // cooldown=50ms, 3 levels (TIMED_OUT→THROTTLED→WARNED→NONE) = 150ms
+            await new Promise(r => setTimeout(r, 200));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+            // timeoutCount should STILL be 1 (timeoutMemoryMs=500 hasn't elapsed)
+            const state2 = engine.getState('conn1');
+            assert.equal(state2.timeoutCount, 1);
+            // Round 2: re-spam. One more timeout should trigger kick (2/2)
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn1');
+            const state3 = engine.getState('conn1');
+            assert.equal(state3.level, EscalationLevel.KICKED);
+        });
+        it('timeoutCount resets after timeoutMemoryMs expires', async () => {
+            const engine = new EscalationEngine({
+                warnAfterViolations: 2,
+                throttleAfterViolations: 4,
+                timeoutAfterViolations: 6,
+                kickAfterTimeouts: 2,
+                throttleDurationMs: 5000,
+                timeoutDurationMs: 30,
+                violationWindowMs: 200,
+                cooldownMs: 50,
+                timeoutMemoryMs: 100, // short memory for testing
+            });
+            // Escalate to timeout
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation('conn1');
+            assert.equal(engine.getState('conn1').timeoutCount, 1);
+            // Wait for full decay AND timeout memory expiry
+            await new Promise(r => setTimeout(r, 200));
+            assert.equal(engine.getLevel('conn1'), EscalationLevel.NONE);
+            // timeoutCount should now be 0 (memory expired)
+            assert.equal(engine.getState('conn1').timeoutCount, 0);
+        });
+    });
+    describe('identity invariants', () => {
+        it('persistent identity preserves escalation across reconnections', () => {
+            const engine = makeEngine();
+            // Agent with persistent ID escalates to warned
+            const persistentId = 'ed25519:abc123def456';
+            for (let i = 0; i < 3; i++)
+                engine.recordViolation(persistentId);
+            assert.equal(engine.getLevel(persistentId), EscalationLevel.WARNED);
+            // Simulate disconnect (don't remove state — this is intentional)
+            // Reconnect with same persistent ID
+            // State should still be warned
+            assert.equal(engine.getLevel(persistentId), EscalationLevel.WARNED);
+            // Further violations continue from existing state
+            for (let i = 0; i < 3; i++)
+                engine.recordViolation(persistentId);
+            assert.equal(engine.getLevel(persistentId), EscalationLevel.THROTTLED);
+        });
+        it('ephemeral agents get fresh state with new IDs', () => {
+            const engine = makeEngine();
+            // Ephemeral agent escalates
+            const ephemeralId1 = 'anon_abc123';
+            for (let i = 0; i < 3; i++)
+                engine.recordViolation(ephemeralId1);
+            assert.equal(engine.getLevel(ephemeralId1), EscalationLevel.WARNED);
+            // Ephemeral agent disconnects and reconnects with new random ID
+            const ephemeralId2 = 'anon_xyz789';
+            // New ID has no state — starts fresh
+            assert.equal(engine.getLevel(ephemeralId2), EscalationLevel.NONE);
+            const result = engine.recordViolation(ephemeralId2);
+            assert.equal(result.type, 'allow'); // first violation, no escalation
+        });
+        it('old ephemeral state does not leak to new connections', () => {
+            const engine = makeEngine();
+            // Escalate an ephemeral agent to throttled
+            const oldId = 'anon_old';
+            for (let i = 0; i < 6; i++)
+                engine.recordViolation(oldId);
+            assert.equal(engine.getLevel(oldId), EscalationLevel.THROTTLED);
+            // A completely different ephemeral agent should not be affected
+            const newId = 'anon_new';
+            assert.equal(engine.getLevel(newId), EscalationLevel.NONE);
+            assert.equal(engine.getThrottleDelay(newId), 0);
+            assert.equal(engine.isTimedOut(newId), false);
+        });
+    });
+    describe('default options', () => {
+        it('works with default configuration', () => {
+            const engine = new EscalationEngine();
+            const result = engine.recordViolation('conn1');
+            assert.equal(result.type, 'allow');
+        });
+    });
+});
+//# sourceMappingURL=escalation.test.js.map