chatroom-cli 1.30.1 → 1.32.1

package/dist/infrastructure/services/harness-spawning/rate-limiter.test.js

@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SpawnRateLimiter } from './rate-limiter.js';
+describe('SpawnRateLimiter', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    // ─── Token Bucket Depletion ────────────────────────────────────────────────
+    describe('token bucket depletion', () => {
+        it('allows spawns up to maxTokens and then rejects', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 3,
+                initialTokens: 3,
+                refillRateMs: 60_000,
+            });
+            const chatroomId = 'room-1';
+            const reason = 'platform.crash_recovery';
+            // Consume all 3 tokens
+            expect(limiter.tryConsume(chatroomId, reason)).toEqual({ allowed: true });
+            expect(limiter.tryConsume(chatroomId, reason)).toEqual({ allowed: true });
+            expect(limiter.tryConsume(chatroomId, reason)).toEqual({ allowed: true });
+            // 4th should be rejected
+            const result = limiter.tryConsume(chatroomId, reason);
+            expect(result.allowed).toBe(false);
+            expect(result.retryAfterMs).toBeGreaterThan(0);
+        });
+        it('rejects subsequent calls when tokens are exhausted', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 1,
+                initialTokens: 1,
+                refillRateMs: 60_000,
+            });
+            limiter.tryConsume('room-A', 'platform.crash_recovery');
+            const result = limiter.tryConsume('room-A', 'platform.crash_recovery');
+            expect(result.allowed).toBe(false);
+        });
+    });
+    // ─── User-Initiated Bypass ────────────────────────────────────────────────
+    describe('user-initiated bypass', () => {
+        it('always allows spawns with a reason starting with "user."', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 0,
+                initialTokens: 0,
+                refillRateMs: 60_000,
+            });
+            // Even with 0 tokens, user-initiated must be allowed
+            expect(limiter.tryConsume('room-1', 'user.manual')).toEqual({ allowed: true });
+            expect(limiter.tryConsume('room-1', 'user.restart')).toEqual({ allowed: true });
+        });
+        it('does NOT bypass for reasons that do not start with "user."', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 0,
+                initialTokens: 0,
+                refillRateMs: 60_000,
+            });
+            expect(limiter.tryConsume('room-1', 'platform.crash_recovery').allowed).toBe(false);
+            expect(limiter.tryConsume('room-1', 'system.restart').allowed).toBe(false);
+        });
+    });
+    // ─── Token Refill Over Time ───────────────────────────────────────────────
+    describe('token refill over time', () => {
+        it('refills tokens after the refill interval', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 5,
+                initialTokens: 1,
+                refillRateMs: 60_000,
+            });
+            const chatroomId = 'room-refill';
+            const reason = 'platform.restart';
+            // Consume the only token
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(true);
+            // Now empty — should reject
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(false);
+            // Advance time by one refill interval
+            vi.advanceTimersByTime(60_000);
+            // Should have 1 token again
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(true);
+        });
+        it('refills multiple tokens after multiple intervals', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 5,
+                initialTokens: 0,
+                refillRateMs: 10_000,
+            });
+            const chatroomId = 'room-multi-refill';
+            const reason = 'platform.restart';
+            // Prime the bucket by calling getStatus before advancing time
+            limiter.getStatus(chatroomId);
+            // Advance 3 refill intervals
+            vi.advanceTimersByTime(30_000);
+            // Should now have 3 tokens
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(true);
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(true);
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(true);
+            expect(limiter.tryConsume(chatroomId, reason).allowed).toBe(false);
+        });
+        it('does not exceed maxTokens when refilling', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 3,
+                initialTokens: 2,
+                refillRateMs: 10_000,
+            });
+            const chatroomId = 'room-cap';
+            const reason = 'platform.restart';
+            // Prime the bucket before advancing time
+            limiter.getStatus(chatroomId);
+            // Advance 5 refill intervals — would overflow without capping
+            vi.advanceTimersByTime(50_000);
+            const status = limiter.getStatus(chatroomId);
+            expect(status.remaining).toBe(3);
+            expect(status.total).toBe(3);
+        });
+    });
+    // ─── Low-Token Warning ────────────────────────────────────────────────────
+    describe('low token warning', () => {
+        it('logs a warning when tokens drop to the threshold (≤ 1)', () => {
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 3,
+                initialTokens: 3,
+                refillRateMs: 60_000,
+            });
+            const chatroomId = 'room-warn';
+            const reason = 'platform.restart';
+            // First two spawns — no warning yet
+            limiter.tryConsume(chatroomId, reason); // 2 remaining
+            expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining('tokens running low'));
+            limiter.tryConsume(chatroomId, reason); // 1 remaining — warning
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('tokens running low'));
+        });
+        it('logs a rate-limit warning when bucket is exhausted', () => {
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 1,
+                initialTokens: 1,
+                refillRateMs: 60_000,
+            });
+            limiter.tryConsume('room-x', 'platform.restart'); // consume
+            limiter.tryConsume('room-x', 'platform.restart'); // rate-limited
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('rate-limited'));
+        });
+    });
+    // ─── Independent Buckets Per Chatroom ────────────────────────────────────
+    describe('independent buckets per chatroom', () => {
+        it('tracks tokens independently for different chatrooms', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 2,
+                initialTokens: 2,
+                refillRateMs: 60_000,
+            });
+            const reason = 'platform.restart';
+            // Exhaust room-A
+            limiter.tryConsume('room-A', reason);
+            limiter.tryConsume('room-A', reason);
+            expect(limiter.tryConsume('room-A', reason).allowed).toBe(false);
+            // room-B should still have a full bucket
+            expect(limiter.tryConsume('room-B', reason).allowed).toBe(true);
+            expect(limiter.tryConsume('room-B', reason).allowed).toBe(true);
+            expect(limiter.tryConsume('room-B', reason).allowed).toBe(false);
+        });
+        it('getStatus returns independent status per chatroom', () => {
+            const limiter = new SpawnRateLimiter({
+                maxTokens: 5,
+                initialTokens: 5,
+                refillRateMs: 60_000,
+            });
+            limiter.tryConsume('room-1', 'platform.restart');
+            limiter.tryConsume('room-1', 'platform.restart');
+            const status1 = limiter.getStatus('room-1');
+            const status2 = limiter.getStatus('room-2');
+            expect(status1.remaining).toBe(3);
+            expect(status2.remaining).toBe(5);
+        });
+    });
+});
+//# sourceMappingURL=rate-limiter.test.js.map

package/dist/infrastructure/services/harness-spawning/rate-limiter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.test.js","sourceRoot":"","sources":["../../../../src/infrastructure/services/harness-spawning/rate-limiter.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,8EAA8E;IAE9E,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;QACtC,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;YACxD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,QAAQ,CAAC;YAC5B,MAAM,MAAM,GAAG,yBAAyB,CAAC;YAEzC,uBAAuB;YACvB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1E,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1E,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAE1E,yBAAyB;YACzB,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YACtD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;YAC5D,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC;YAExD,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC;YACvE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAE7E,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;QACrC,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;YAClE,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YAEH,qDAAqD;YACrD,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/E,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;YACpE,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YAEH,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpF,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAE7E,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;QACtC,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,aAAa,CAAC;YACjC,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAElC,yBAAyB;YACzB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,4BAA4B;YAC5B,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEnE,sCAAsC;YACtC,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAE/B,4BAA4B;YAC5B,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC1D,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,mBAAmB,CAAC;YACvC,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAElC,8DAA8D;YAC9D,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YAE9B,6BAA6B;YAC7B,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAE/B,2BAA2B;YAC3B,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,UAAU,CAAC;YAC9B,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAElC,yCAAyC;YACzC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YAE9B,8DAA8D;YAC9D,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAE/B,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YAC7C,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAE7E,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;YAChE,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,WAAW,CAAC;YAC/B,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAElC,oCAAoC;YACpC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc;YACtD,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAExF,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,wBAAwB;YAChE,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,CAAC,CAAC;QACtF,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;YAC5D,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YAEH,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,UAAU;YAC5D,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,eAAe;YAEjE,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAE5E,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAChD,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAC7D,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAElC,iBAAiB;YACjB,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACrC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEjE,yCAAyC;YACzC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,YAAY,EAAE,MAAM;aACrB,CAAC,CAAC;YAEH,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;YACjD,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;YAEjD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAE5C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.d.ts

@@ -0,0 +1,77 @@
+/**
+ * BaseCLIAgentService — abstract base class for CLI-based remote agent services.
+ *
+ * Provides shared boilerplate for all CLI agent implementations:
+ * - Dependency injection (execSync, spawn, kill)
+ * - Process registry tracking spawned PIDs with context and last-output timestamps
+ * - isInstalled / getVersion (command passed per-call)
+ * - stop / isAlive / getTrackedProcesses / untrack (identical lifecycle across all agents)
+ *
+ * Subclasses must implement:
+ * - listModels(): Promise<string[]>
+ * - spawn(options: SpawnOptions): Promise<SpawnResult>
+ */
+import { spawn } from 'node:child_process';
+import type { RemoteAgentService, SpawnContext, SpawnOptions, SpawnResult, ProcessInfo, VersionInfo } from './remote-agent-service.js';
+export interface CLIAgentServiceDeps {
+    /** Execute a synchronous command (for detection/version/model queries). */
+    execSync: (cmd: string, options?: object) => Buffer;
+    /** Spawn a child process (for agent lifecycle). */
+    spawn: typeof spawn;
+    /** Send a signal to a PID. Throws if process does not exist. */
+    kill: (pid: number, signal: number | string) => boolean;
+}
+export declare abstract class BaseCLIAgentService implements RemoteAgentService {
+    protected readonly deps: CLIAgentServiceDeps;
+    private readonly processes;
+    constructor(deps?: Partial<CLIAgentServiceDeps>);
+    /**
+     * Returns true if the given CLI command is available on this machine.
+     * Uses `which` (Unix) or `where` (Windows) to check.
+     *
+     * Subclasses implement the no-arg `isInstalled()` from RemoteAgentService
+     * by calling this with their specific command name.
+     */
+    protected checkInstalled(command: string): boolean;
+    /**
+     * Returns the version of the given CLI command, parsed as semver.
+     * Runs `<command> --version` and extracts a `major.minor.patch` triple.
+     * Returns null if not installed or version cannot be parsed.
+     *
+     * Subclasses implement the no-arg `getVersion()` from RemoteAgentService
+     * by calling this with their specific command name.
+     */
+    protected checkVersion(command: string): VersionInfo | null;
+    /**
+     * Stop a spawned agent process. Sends SIGTERM to the entire process group,
+     * polls until the process exits, then escalates to SIGKILL if it lingers.
+     */
+    stop(pid: number): Promise<void>;
+    /** Returns true if the given PID is still alive. */
+    isAlive(pid: number): boolean;
+    /** Returns all currently tracked processes with their context and last output timestamp. */
+    getTrackedProcesses(): ProcessInfo[];
+    /** Remove a process from the internal registry (call on cleanup/exit). */
+    untrack(pid: number): void;
+    /**
+     * Add a process to the internal registry.
+     * Returns a reference to the registry entry so callers can update `lastOutputAt`.
+     */
+    protected registerProcess(pid: number, context: SpawnContext): {
+        context: SpawnContext;
+        lastOutputAt: number;
+    };
+    /**
+     * Remove a process from the internal registry.
+     * Equivalent to `untrack()` but intended for internal use by subclasses.
+     */
+    protected deleteProcess(pid: number): void;
+    abstract readonly id: string;
+    abstract readonly displayName: string;
+    abstract readonly command: string;
+    abstract isInstalled(): boolean;
+    abstract getVersion(): VersionInfo | null;
+    abstract listModels(): Promise<string[]>;
+    abstract spawn(options: SpawnOptions): Promise<SpawnResult>;
+}
+//# sourceMappingURL=base-cli-agent-service.d.ts.map

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cli-agent-service.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/remote-agents/base-cli-agent-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAY,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,mDAAmD;IACnD,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gEAAgE;IAChE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC;CACzD;AAiBD,8BAAsB,mBAAoB,YAAW,kBAAkB;IACrE,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsE;gBAEpF,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAI/C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAUlD;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAwB3D;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtC,oDAAoD;IACpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS7B,4FAA4F;IAC5F,mBAAmB,IAAI,WAAW,EAAE;IAQpC,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B;;;OAGG;IACH,SAAS,CAAC,eAAe,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,GACpB;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAMlD;;;OAGG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAElC,QAAQ,CAAC,WAAW,IAAI,OAAO;IAC/B,QAAQ,CAAC,UAAU,IAAI,WAAW,GAAG,IAAI;IACzC,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;CAC5D"}

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.js

@@ -0,0 +1,149 @@
+/**
+ * BaseCLIAgentService — abstract base class for CLI-based remote agent services.
+ *
+ * Provides shared boilerplate for all CLI agent implementations:
+ * - Dependency injection (execSync, spawn, kill)
+ * - Process registry tracking spawned PIDs with context and last-output timestamps
+ * - isInstalled / getVersion (command passed per-call)
+ * - stop / isAlive / getTrackedProcesses / untrack (identical lifecycle across all agents)
+ *
+ * Subclasses must implement:
+ * - listModels(): Promise<string[]>
+ * - spawn(options: SpawnOptions): Promise<SpawnResult>
+ */
+import { spawn, execSync } from 'node:child_process';
+function defaultDeps() {
+    return {
+        execSync,
+        spawn,
+        kill: (pid, signal) => process.kill(pid, signal),
+    };
+}
+// ─── Constants ────────────────────────────────────────────────────────────────
+const KILL_TIMEOUT_MS = 5000;
+const POLL_INTERVAL_MS = 200;
+// ─── Base Class ───────────────────────────────────────────────────────────────
+export class BaseCLIAgentService {
+    deps;
+    processes = new Map();
+    constructor(deps) {
+        this.deps = { ...defaultDeps(), ...deps };
+    }
+    /**
+     * Returns true if the given CLI command is available on this machine.
+     * Uses `which` (Unix) or `where` (Windows) to check.
+     *
+     * Subclasses implement the no-arg `isInstalled()` from RemoteAgentService
+     * by calling this with their specific command name.
+     */
+    checkInstalled(command) {
+        try {
+            const checkCmd = process.platform === 'win32' ? `where ${command}` : `which ${command}`;
+            this.deps.execSync(checkCmd, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Returns the version of the given CLI command, parsed as semver.
+     * Runs `<command> --version` and extracts a `major.minor.patch` triple.
+     * Returns null if not installed or version cannot be parsed.
+     *
+     * Subclasses implement the no-arg `getVersion()` from RemoteAgentService
+     * by calling this with their specific command name.
+     */
+    checkVersion(command) {
+        try {
+            // Use shell redirect `2>&1` to merge stderr into stdout so CLIs that
+            // write version info to stderr (e.g. Pi) are also captured.
+            const output = this.deps
+                .execSync(`${command} --version 2>&1`, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 5000,
+            })
+                .toString()
+                .trim();
+            const match = output.match(/v?(\d+)\.(\d+)\.(\d+)/);
+            if (!match)
+                return null;
+            return {
+                version: `${match[1]}.${match[2]}.${match[3]}`,
+                major: parseInt(match[1], 10),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Stop a spawned agent process. Sends SIGTERM to the entire process group,
+     * polls until the process exits, then escalates to SIGKILL if it lingers.
+     */
+    async stop(pid) {
+        // SIGTERM → entire process group (negative PID)
+        try {
+            this.deps.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            return; // Already dead
+        }
+        const deadline = Date.now() + KILL_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            try {
+                this.deps.kill(pid, 0);
+            }
+            catch {
+                return; // Exited
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+        // Still alive — SIGKILL
+        try {
+            this.deps.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            // May have exited between check and kill
+        }
+    }
+    /** Returns true if the given PID is still alive. */
+    isAlive(pid) {
+        try {
+            this.deps.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Returns all currently tracked processes with their context and last output timestamp. */
+    getTrackedProcesses() {
+        return Array.from(this.processes.entries()).map(([pid, entry]) => ({
+            pid,
+            context: entry.context,
+            lastOutputAt: entry.lastOutputAt,
+        }));
+    }
+    /** Remove a process from the internal registry (call on cleanup/exit). */
+    untrack(pid) {
+        this.processes.delete(pid);
+    }
+    /**
+     * Add a process to the internal registry.
+     * Returns a reference to the registry entry so callers can update `lastOutputAt`.
+     */
+    registerProcess(pid, context) {
+        const entry = { context, lastOutputAt: Date.now() };
+        this.processes.set(pid, entry);
+        return entry;
+    }
+    /**
+     * Remove a process from the internal registry.
+     * Equivalent to `untrack()` but intended for internal use by subclasses.
+     */
+    deleteProcess(pid) {
+        this.processes.delete(pid);
+    }
+}
+//# sourceMappingURL=base-cli-agent-service.js.map

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cli-agent-service.js","sourceRoot":"","sources":["../../../../src/infrastructure/services/remote-agents/base-cli-agent-service.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base-cli-agent-service.test.d.ts.map

package/dist/infrastructure/services/remote-agents/base-cli-agent-service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cli-agent-service.test.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/remote-agents/base-cli-agent-service.test.ts"],"names":[],"mappings":""}