@soleri/core 9.0.3 → 9.2.0

package/src/llm/utils.test.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CircuitBreaker, CircuitOpenError, computeDelay, retry, parseRateLimitHeaders } from './utils.js';
+import { LLMError } from './types.js';
+
+// ─── CircuitOpenError ───────────────────────────────────────────────
+
+describe('CircuitOpenError', () => {
+  it('should include the breaker name in the message', () => {
+    const err = new CircuitOpenError('test-breaker');
+    expect(err.message).toContain('test-breaker');
+    expect(err.name).toBe('CircuitOpenError');
+  });
+
+  it('should not be retryable', () => {
+    const err = new CircuitOpenError('x');
+    expect(err.retryable).toBe(false);
+  });
+
+  it('should be an instance of CircuitOpenError', () => {
+    const err = new CircuitOpenError('x');
+    expect(err).toBeInstanceOf(CircuitOpenError);
+    expect(err).toBeInstanceOf(Error);
+  });
+});
+
+// ─── CircuitBreaker ─────────────────────────────────────────────────
+
+describe('CircuitBreaker', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('should start in closed state', () => {
+    const cb = new CircuitBreaker({ name: 'test' });
+    const snap = cb.getState();
+    expect(snap.state).toBe('closed');
+    expect(snap.failureCount).toBe(0);
+  });
+
+  it('should pass through successful calls in closed state', async () => {
+    const cb = new CircuitBreaker({ name: 'test' });
+    const result = await cb.call(async () => 42);
+    expect(result).toBe(42);
+  });
+
+  it('should rethrow errors from the wrapped function', async () => {
+    const cb = new CircuitBreaker({ name: 'test' });
+    await expect(cb.call(async () => { throw new Error('boom'); })).rejects.toThrow('boom');
+  });
+
+  it('should not count non-retryable errors as failures', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 2 });
+    const nonRetryable = new Error('not retryable');
+
+    for (let i = 0; i < 5; i++) {
+      await expect(cb.call(async () => { throw nonRetryable; })).rejects.toThrow();
+    }
+    expect(cb.getState().state).toBe('closed');
+  });
+
+  it('should open after reaching failure threshold with retryable errors', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 2 });
+    const retryableErr = new LLMError('rate limited', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    expect(cb.isOpen()).toBe(true);
+  });
+
+  it('should reject calls when open', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 1, resetTimeoutMs: 999_999 });
+    const retryableErr = new LLMError('fail', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    await expect(cb.call(async () => 'ok')).rejects.toThrow(CircuitOpenError);
+  });
+
+  it('should transition to half-open after reset timeout', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 1, resetTimeoutMs: 10 });
+    const retryableErr = new LLMError('fail', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    expect(cb.isOpen()).toBe(true);
+
+    // Wait for reset timeout
+    await new Promise((r) => setTimeout(r, 20));
+    expect(cb.isOpen()).toBe(false); // shouldProbe returns true
+    expect(cb.getState().state).toBe('half-open');
+  });
+
+  it('should close on success after half-open probe', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 1, resetTimeoutMs: 10 });
+    const retryableErr = new LLMError('fail', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    await new Promise((r) => setTimeout(r, 20));
+
+    const result = await cb.call(async () => 'recovered');
+    expect(result).toBe('recovered');
+    expect(cb.getState().state).toBe('closed');
+  });
+
+  it('should re-open on failure in half-open state', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 1, resetTimeoutMs: 10 });
+    const retryableErr = new LLMError('fail', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    await new Promise((r) => setTimeout(r, 20));
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    expect(cb.getState().state).toBe('open');
+  });
+
+  it('should reset state completely via reset()', async () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 1, resetTimeoutMs: 999_999 });
+    const retryableErr = new LLMError('fail', { retryable: true });
+
+    await expect(cb.call(async () => { throw retryableErr; })).rejects.toThrow();
+    expect(cb.isOpen()).toBe(true);
+
+    cb.reset();
+    expect(cb.getState().state).toBe('closed');
+    expect(cb.getState().failureCount).toBe(0);
+    expect(cb.getState().lastFailureAt).toBeNull();
+  });
+
+  it('should record failures synchronously via recordFailure()', () => {
+    const cb = new CircuitBreaker({ name: 'test', failureThreshold: 2 });
+    cb.recordFailure();
+    expect(cb.getState().failureCount).toBe(1);
+    expect(cb.getState().state).toBe('closed');
+
+    cb.recordFailure();
+    expect(cb.getState().state).toBe('open');
+  });
+
+  it('should use default config values when none provided', () => {
+    const cb = new CircuitBreaker();
+    const snap = cb.getState();
+    expect(snap.state).toBe('closed');
+  });
+});
+
+// ─── computeDelay ───────────────────────────────────────────────────
+
+describe('computeDelay', () => {
+  it('should use retryAfterMs from error when available', () => {
+    const error = { retryAfterMs: 5000 };
+    const config = { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 30000, jitter: 0 };
+    expect(computeDelay(error, 0, config)).toBe(5000);
+  });
+
+  it('should cap retryAfterMs at maxDelayMs', () => {
+    const error = { retryAfterMs: 100_000 };
+    const config = { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 30000, jitter: 0 };
+    expect(computeDelay(error, 0, config)).toBe(30000);
+  });
+
+  it('should compute exponential backoff without jitter', () => {
+    const config = { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 30000, jitter: 0 };
+    expect(computeDelay({}, 0, config)).toBe(1000);
+    expect(computeDelay({}, 1, config)).toBe(2000);
+    expect(computeDelay({}, 2, config)).toBe(4000);
+  });
+
+  it('should cap exponential delay at maxDelayMs', () => {
+    const config = { maxAttempts: 10, baseDelayMs: 1000, maxDelayMs: 5000, jitter: 0 };
+    expect(computeDelay({}, 10, config)).toBe(5000);
+  });
+
+  it('should apply jitter within range', () => {
+    const config = { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 30000, jitter: 0.5 };
+    const delays = Array.from({ length: 50 }, () => computeDelay({}, 0, config));
+    expect(delays.every((d) => d >= 500 && d <= 1500)).toBe(true);
+  });
+
+  it('should never return negative delay', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+    const config = { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 30000, jitter: 1 };
+    expect(computeDelay({}, 0, config)).toBeGreaterThanOrEqual(0);
+    vi.restoreAllMocks();
+  });
+});
+
+// ─── retry ──────────────────────────────────────────────────────────
+
+describe('retry', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterAll(() => {
+    vi.useRealTimers();
+  });
+
+  it('should return on first success', async () => {
+    vi.useRealTimers();
+    const fn = vi.fn().mockResolvedValue('ok');
+    const result = await retry(fn);
+    expect(result).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should throw if maxAttempts < 1', async () => {
+    vi.useRealTimers();
+    await expect(retry(async () => 'ok', { maxAttempts: 0 })).rejects.toThrow('maxAttempts must be >= 1');
+  });
+
+  it('should throw non-retryable errors immediately', async () => {
+    vi.useRealTimers();
+    const fn = vi.fn().mockRejectedValue(new Error('fatal'));
+    await expect(retry(fn, { maxAttempts: 3 })).rejects.toThrow('fatal');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should retry retryable errors up to maxAttempts', async () => {
+    vi.useRealTimers();
+    const retryableErr = new LLMError('rate limited', { retryable: true });
+    const fn = vi.fn().mockRejectedValue(retryableErr);
+    await expect(
+      retry(fn, { maxAttempts: 2, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 }),
+    ).rejects.toThrow('rate limited');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should succeed on retry after initial failures', async () => {
+    vi.useRealTimers();
+    const retryableErr = new LLMError('transient', { retryable: true });
+    const fn = vi.fn()
+      .mockRejectedValueOnce(retryableErr)
+      .mockResolvedValueOnce('recovered');
+
+    const result = await retry(fn, { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 });
+    expect(result).toBe('recovered');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should call onRetry callback on each retry', async () => {
+    vi.useRealTimers();
+    const retryableErr = new LLMError('transient', { retryable: true });
+    const onRetry = vi.fn();
+    const fn = vi.fn()
+      .mockRejectedValueOnce(retryableErr)
+      .mockResolvedValueOnce('ok');
+
+    await retry(fn, { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 1, jitter: 0, onRetry });
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry).toHaveBeenCalledWith(retryableErr, 1, expect.any(Number));
+  });
+
+  it('should respect custom shouldRetry predicate', async () => {
+    vi.useRealTimers();
+    const customErr = new Error('custom');
+    const fn = vi.fn().mockRejectedValue(customErr);
+    const shouldRetry = vi.fn().mockReturnValue(true);
+
+    await expect(
+      retry(fn, { maxAttempts: 2, baseDelayMs: 1, maxDelayMs: 1, jitter: 0, shouldRetry }),
+    ).rejects.toThrow('custom');
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(shouldRetry).toHaveBeenCalled();
+  });
+});
+
+// Need this import for afterAll
+import { afterAll } from 'vitest';
+
+// ─── parseRateLimitHeaders ──────────────────────────────────────────
+
+describe('parseRateLimitHeaders', () => {
+  function makeHeaders(obj: Record<string, string>): Headers {
+    return new Headers(obj);
+  }
+
+  it('should parse remaining requests header', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-remaining-requests': '42' }));
+    expect(info.remaining).toBe(42);
+  });
+
+  it('should return null for missing remaining header', () => {
+    const info = parseRateLimitHeaders(makeHeaders({}));
+    expect(info.remaining).toBeNull();
+  });
+
+  it('should return null for non-numeric remaining header', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-remaining-requests': 'abc' }));
+    expect(info.remaining).toBeNull();
+  });
+
+  it('should parse retry-after header as seconds', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'retry-after': '2.5' }));
+    expect(info.retryAfterMs).toBe(2500);
+  });
+
+  it('should return null for non-numeric retry-after', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'retry-after': 'invalid' }));
+    expect(info.retryAfterMs).toBeNull();
+  });
+
+  it('should parse reset duration with minutes and seconds', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-reset-requests': '2m30s' }));
+    expect(info.resetMs).toBe(2 * 60_000 + 30 * 1000);
+  });
+
+  it('should parse reset duration with milliseconds', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-reset-requests': '500ms' }));
+    expect(info.resetMs).toBe(500);
+  });
+
+  it('should parse reset duration with seconds only', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-reset-requests': '45s' }));
+    expect(info.resetMs).toBe(45000);
+  });
+
+  it('should return null for unparseable reset duration', () => {
+    const info = parseRateLimitHeaders(makeHeaders({ 'x-ratelimit-reset-requests': 'unknown' }));
+    expect(info.resetMs).toBeNull();
+  });
+
+  it('should return all nulls when no headers present', () => {
+    const info = parseRateLimitHeaders(makeHeaders({}));
+    expect(info.remaining).toBeNull();
+    expect(info.resetMs).toBeNull();
+    expect(info.retryAfterMs).toBeNull();
+  });
+});

package/src/llm/utils.ts

@@ -182,6 +182,7 @@ export async function retry<T>(fn: () => Promise<T>, config?: Partial<RetryConfi
 
   for (let attempt = 0; attempt < resolved.maxAttempts; attempt++) {
     try {
+      // oxlint-disable-next-line eslint(no-await-in-loop)
       return await fn();
     } catch (error) {
       lastError = error;
@@ -193,6 +194,7 @@ export async function retry<T>(fn: () => Promise<T>, config?: Partial<RetryConfi
       const delay = computeDelay(error, attempt, resolved);
       resolved.onRetry?.(error, attempt + 1, delay);
 
+      // oxlint-disable-next-line eslint(no-await-in-loop)
       await sleep(delay);
     }
   }

package/src/{__tests__ → logging}/logger.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { mkdirSync, rmSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { Logger, createLogger } from '../logging/logger.js';
+import { Logger, createLogger } from './logger.js';
 
 describe('Logger', () => {
   let errorSpy: ReturnType<typeof vi.spyOn>;
@@ -18,96 +18,82 @@ describe('Logger', () => {
     delete process.env.SOLERI_LOG_LEVEL;
   });
 
-  it('should default to info level', () => {
+  it('defaults to info level (debug suppressed, info visible)', () => {
     const logger = createLogger();
     logger.debug('hidden');
     logger.info('visible');
-
     expect(errorSpy).toHaveBeenCalledTimes(1);
     expect(errorSpy).toHaveBeenCalledWith('[Soleri][INFO] visible');
   });
 
-  it('should suppress messages below configured level', () => {
-    const logger = createLogger({ level: 'warn' });
+  it('suppresses below configured level', () => {
+    const logger = createLogger({ level: 'error' });
     logger.debug('d');
     logger.info('i');
     logger.warn('w');
     logger.error('e');
-
-    expect(errorSpy).toHaveBeenCalledTimes(1); // error
-    expect(warnSpy).toHaveBeenCalledTimes(1); // warn
-    expect(warnSpy).toHaveBeenCalledWith('[Soleri][WARN] w');
-    expect(errorSpy).toHaveBeenCalledWith('[Soleri][ERROR] e');
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).not.toHaveBeenCalled();
   });
 
-  it('should output everything at debug level', () => {
+  it('shows everything at debug level', () => {
     const logger = createLogger({ level: 'debug' });
     logger.debug('d');
     logger.info('i');
     logger.warn('w');
     logger.error('e');
-
-    // debug, info, error go through console.error; warn goes through console.warn
-    expect(errorSpy).toHaveBeenCalledTimes(3);
+    expect(errorSpy).toHaveBeenCalledTimes(3); // debug, info, error
     expect(warnSpy).toHaveBeenCalledTimes(1);
   });
 
-  it('should route all output to stderr (not stdout)', () => {
+  it('never uses console.log (stdout reserved for MCP)', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     const logger = createLogger({ level: 'debug' });
     logger.debug('d');
     logger.info('i');
     logger.warn('w');
     logger.error('e');
-
     expect(logSpy).not.toHaveBeenCalled();
   });
 
-  it('should use custom prefix', () => {
-    const logger = createLogger({ prefix: '[my-agent]' });
-    logger.info('hello');
-
-    expect(errorSpy).toHaveBeenCalledWith('[my-agent][INFO] hello');
+  it('uses custom prefix', () => {
+    const logger = createLogger({ prefix: '[MyAgent]' });
+    logger.info('hi');
+    expect(errorSpy).toHaveBeenCalledWith('[MyAgent][INFO] hi');
   });
 
-  it('should include context in log output', () => {
+  it('passes context object alongside message', () => {
     const logger = createLogger();
-    logger.info('msg', { key: 'value' });
-
-    expect(errorSpy).toHaveBeenCalledWith('[Soleri][INFO] msg', { key: 'value' });
+    logger.info('event', { key: 'val' });
+    expect(errorSpy).toHaveBeenCalledWith('[Soleri][INFO] event', { key: 'val' });
   });
 
-  it('should respect SOLERI_LOG_LEVEL env var', () => {
-    process.env.SOLERI_LOG_LEVEL = 'error';
+  it('respects SOLERI_LOG_LEVEL env var', () => {
+    process.env.SOLERI_LOG_LEVEL = 'warn';
     const logger = createLogger();
     logger.info('hidden');
-    logger.error('visible');
-
-    expect(errorSpy).toHaveBeenCalledTimes(1);
-    expect(errorSpy).toHaveBeenCalledWith('[Soleri][ERROR] visible');
+    logger.warn('visible');
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
   });
 
-  it('should prefer explicit level over env var', () => {
+  it('prefers explicit level over env var', () => {
     process.env.SOLERI_LOG_LEVEL = 'error';
     const logger = createLogger({ level: 'debug' });
     logger.debug('visible');
-
     expect(errorSpy).toHaveBeenCalledTimes(1);
   });
 
-  it('should fall back to info level for invalid SOLERI_LOG_LEVEL', () => {
-    process.env.SOLERI_LOG_LEVEL = 'verbose'; // invalid
+  it('falls back to info for invalid SOLERI_LOG_LEVEL', () => {
+    process.env.SOLERI_LOG_LEVEL = 'banana';
     const logger = createLogger();
     logger.debug('hidden');
     logger.info('visible');
-
     expect(errorSpy).toHaveBeenCalledTimes(1);
-    expect(errorSpy).toHaveBeenCalledWith('[Soleri][INFO] visible');
   });
 
-  it('createLogger with no args returns a Logger instance', () => {
-    const logger = createLogger();
-    expect(logger).toBeInstanceOf(Logger);
+  it('createLogger returns Logger instance', () => {
+    expect(createLogger()).toBeInstanceOf(Logger);
   });
 });
 
@@ -117,7 +103,7 @@ describe('Logger file logging', () => {
   beforeEach(() => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     vi.spyOn(console, 'warn').mockImplementation(() => {});
-    tempDir = join(tmpdir(), `logger-test-${Date.now()}`);
+    tempDir = join(tmpdir(), `logger-colocated-${Date.now()}-${Math.random().toString(36).slice(2)}`);
     mkdirSync(tempDir, { recursive: true });
   });
 
@@ -126,7 +112,7 @@ describe('Logger file logging', () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
-  it('should create log directory and write log files', () => {
+  it('creates log directory and writes daily log file', () => {
     const logDir = join(tempDir, 'logs');
     const logger = createLogger({ fileLogDir: logDir });
     logger.info('test message');
@@ -139,62 +125,55 @@ describe('Logger file logging', () => {
     expect(content).toContain('[INFO] test message');
   });
 
-  it('should include context in file output', () => {
+  it('includes JSON-serialized context in file output', () => {
     const logDir = join(tempDir, 'logs');
     const logger = createLogger({ fileLogDir: logDir });
-    logger.info('event', { action: 'test' });
+    logger.info('action', { id: 42 });
 
-    const logFile = readdirSync(logDir).find((f) => f.endsWith('.log'));
-    expect(logFile).toBeDefined();
-    const content = readFileSync(join(logDir, logFile!), 'utf-8');
-    expect(content).toContain('"action":"test"');
+    const logFile = readdirSync(logDir).find((f) => f.endsWith('.log'))!;
+    const content = readFileSync(join(logDir, logFile), 'utf-8');
+    expect(content).toContain('"id":42');
   });
 
-  it('enableFileLog with custom prefix uses that prefix', () => {
+  it('enableFileLog accepts custom prefix for filename', () => {
     const logDir = join(tempDir, 'logs');
     const logger = createLogger();
     logger.enableFileLog(logDir, 'custom');
     logger.info('test');
 
-    const logFile = readdirSync(logDir).find((f) => f.endsWith('.log'));
-    expect(logFile).toBeDefined();
+    const logFile = readdirSync(logDir).find((f) => f.endsWith('.log'))!;
     expect(logFile).toMatch(/^custom-/);
   });
 
-  it('should prune log files older than 7 days', () => {
+  it('prunes log files older than 7 days', () => {
     const logDir = join(tempDir, 'logs');
     mkdirSync(logDir, { recursive: true });
 
-    // Create an "old" log file (10 days ago)
     const oldDate = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
-    writeFileSync(join(logDir, `agent-${oldDate}.log`), 'old log\n');
+    writeFileSync(join(logDir, `agent-${oldDate}.log`), 'old\n');
 
-    // Create a "recent" log file (2 days ago)
     const recentDate = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
-    writeFileSync(join(logDir, `agent-${recentDate}.log`), 'recent log\n');
+    writeFileSync(join(logDir, `agent-${recentDate}.log`), 'recent\n');
 
-    // enableFileLog triggers pruning
     const logger = createLogger();
     logger.enableFileLog(logDir);
 
     const files = readdirSync(logDir).filter((f) => f.endsWith('.log'));
-
-    // Old file should be pruned, recent + today should remain
     expect(files).not.toContain(`agent-${oldDate}.log`);
     expect(files).toContain(`agent-${recentDate}.log`);
   });
 
-  it('should not prune files from different prefix', () => {
+  it('does not prune files with different prefix', () => {
     const logDir = join(tempDir, 'logs');
     mkdirSync(logDir, { recursive: true });
 
     const oldDate = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
-    writeFileSync(join(logDir, `other-${oldDate}.log`), 'other log\n');
+    writeFileSync(join(logDir, `other-${oldDate}.log`), 'keep\n');
 
     const logger = createLogger();
     logger.enableFileLog(logDir);
 
-    const files = readdirSync(logDir).filter((f) => f.endsWith('.log'));
+    const files = readdirSync(logDir);
     expect(files).toContain(`other-${oldDate}.log`);
   });
 });