@supaku/agentfactory-linear 0.7.18 → 0.7.20

package/dist/src/circuit-breaker.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Circuit Breaker for Linear API calls
+ *
+ * Prevents wasting rate limit quota on requests that are guaranteed to fail
+ * (e.g., expired OAuth tokens, revoked access). Implements the standard
+ * closed → open → half-open state machine.
+ *
+ * State machine:
+ *   closed    → all calls proceed; auth failures increment counter;
+ *               at threshold → open
+ *   open      → all calls throw CircuitOpenError immediately (zero quota);
+ *               after resetTimeoutMs → half-open
+ *   half-open → one probe call allowed; success → closed;
+ *               failure → open (with exponential backoff on reset timeout)
+ */
+import { CircuitOpenError } from './errors.js';
+import type { CircuitBreakerConfig, CircuitBreakerStrategy } from './types.js';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: Required<CircuitBreakerConfig>;
+export declare class CircuitBreaker implements CircuitBreakerStrategy {
+    private _state;
+    private consecutiveFailures;
+    private openedAt;
+    private currentResetTimeoutMs;
+    private probeInFlight;
+    private readonly config;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    get state(): CircuitState;
+    /**
+     * Check if a call is allowed to proceed.
+     * In half-open state, only one probe call is allowed at a time.
+     */
+    canProceed(): boolean;
+    /**
+     * Record a successful API call. Resets the circuit to closed.
+     */
+    recordSuccess(): void;
+    /**
+     * Record an auth failure. May trip the circuit to open.
+     * Called after isAuthError() returns true, so the error is already vetted.
+     */
+    recordAuthFailure(_statusCode?: number): void;
+    /**
+     * Check if an error is an auth/rate-limit error that should count as a circuit failure.
+     *
+     * Detects:
+     * - HTTP status codes in authErrorCodes (400, 401, 403)
+     * - Linear GraphQL RATELIMITED error code in response body
+     * - Linear SDK error objects with nested error details
+     */
+    isAuthError(error: unknown): boolean;
+    /**
+     * Extract the status code from an auth error, or 0 if not determinable.
+     */
+    extractStatusCode(error: unknown): number;
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    reset(): void;
+    /**
+     * Get diagnostic info for logging/monitoring.
+     */
+    getStatus(): {
+        state: CircuitState;
+        consecutiveFailures: number;
+        currentResetTimeoutMs: number;
+        msSinceOpened: number | null;
+    };
+    /**
+     * Create a CircuitOpenError with current diagnostic info.
+     */
+    createOpenError(): CircuitOpenError;
+    private trip;
+    private shouldTransitionToHalfOpen;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/src/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAE9E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAE1D,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,oBAAoB,CAMzE,CAAA;AAED,qBAAa,cAAe,YAAW,sBAAsB;IAC3D,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAE3C,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAKlD,IAAI,KAAK,IAAI,YAAY,CAOxB;IAED;;;OAGG;IACH,UAAU,IAAI,OAAO;IAgBrB;;OAEG;IACH,aAAa,IAAI,IAAI;IASrB;;;OAGG;IACH,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAmB7C;;;;;;;OAOG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAyBpC;;OAEG;IACH,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAKzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,SAAS,IAAI;QACX,KAAK,EAAE,YAAY,CAAA;QACnB,mBAAmB,EAAE,MAAM,CAAA;QAC3B,qBAAqB,EAAE,MAAM,CAAA;QAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAC7B;IASD;;OAEG;IACH,eAAe,IAAI,gBAAgB;IAgBnC,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,0BAA0B;CAGnC"}

package/dist/src/circuit-breaker.js

@@ -0,0 +1,229 @@
+/**
+ * Circuit Breaker for Linear API calls
+ *
+ * Prevents wasting rate limit quota on requests that are guaranteed to fail
+ * (e.g., expired OAuth tokens, revoked access). Implements the standard
+ * closed → open → half-open state machine.
+ *
+ * State machine:
+ *   closed    → all calls proceed; auth failures increment counter;
+ *               at threshold → open
+ *   open      → all calls throw CircuitOpenError immediately (zero quota);
+ *               after resetTimeoutMs → half-open
+ *   half-open → one probe call allowed; success → closed;
+ *               failure → open (with exponential backoff on reset timeout)
+ */
+import { CircuitOpenError } from './errors.js';
+export const DEFAULT_CIRCUIT_BREAKER_CONFIG = {
+    failureThreshold: 2,
+    resetTimeoutMs: 60_000,
+    maxResetTimeoutMs: 300_000,
+    backoffMultiplier: 2,
+    authErrorCodes: [400, 401, 403],
+};
+export class CircuitBreaker {
+    _state = 'closed';
+    consecutiveFailures = 0;
+    openedAt = 0;
+    currentResetTimeoutMs;
+    probeInFlight = false;
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CIRCUIT_BREAKER_CONFIG, ...config };
+        this.currentResetTimeoutMs = this.config.resetTimeoutMs;
+    }
+    get state() {
+        // Check if open circuit should transition to half-open
+        if (this._state === 'open' && this.shouldTransitionToHalfOpen()) {
+            this._state = 'half-open';
+            this.probeInFlight = false;
+        }
+        return this._state;
+    }
+    /**
+     * Check if a call is allowed to proceed.
+     * In half-open state, only one probe call is allowed at a time.
+     */
+    canProceed() {
+        const currentState = this.state; // triggers open → half-open check
+        switch (currentState) {
+            case 'closed':
+                return true;
+            case 'open':
+                return false;
+            case 'half-open':
+                // Allow exactly one probe call
+                if (this.probeInFlight)
+                    return false;
+                this.probeInFlight = true;
+                return true;
+        }
+    }
+    /**
+     * Record a successful API call. Resets the circuit to closed.
+     */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.probeInFlight = false;
+        if (this._state !== 'closed') {
+            this._state = 'closed';
+            this.currentResetTimeoutMs = this.config.resetTimeoutMs;
+        }
+    }
+    /**
+     * Record an auth failure. May trip the circuit to open.
+     * Called after isAuthError() returns true, so the error is already vetted.
+     */
+    recordAuthFailure(_statusCode) {
+        this.probeInFlight = false;
+        this.consecutiveFailures++;
+        if (this._state === 'half-open') {
+            // Probe failed — reopen with exponential backoff
+            this.trip();
+            this.currentResetTimeoutMs = Math.min(this.currentResetTimeoutMs * this.config.backoffMultiplier, this.config.maxResetTimeoutMs);
+            return;
+        }
+        if (this.consecutiveFailures >= this.config.failureThreshold) {
+            this.trip();
+        }
+    }
+    /**
+     * Check if an error is an auth/rate-limit error that should count as a circuit failure.
+     *
+     * Detects:
+     * - HTTP status codes in authErrorCodes (400, 401, 403)
+     * - Linear GraphQL RATELIMITED error code in response body
+     * - Linear SDK error objects with nested error details
+     */
+    isAuthError(error) {
+        if (typeof error !== 'object' || error === null)
+            return false;
+        const err = error;
+        // Check HTTP status code
+        const statusCode = extractStatusCode(err);
+        if (statusCode !== null && this.config.authErrorCodes.includes(statusCode)) {
+            return true;
+        }
+        // Check for Linear GraphQL RATELIMITED error
+        if (isGraphQLRateLimited(err)) {
+            return true;
+        }
+        // Check error message for known auth failure patterns
+        const message = err.message ?? '';
+        if (/access denied|unauthorized|forbidden/i.test(message)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Extract the status code from an auth error, or 0 if not determinable.
+     */
+    extractStatusCode(error) {
+        if (typeof error !== 'object' || error === null)
+            return 0;
+        return extractStatusCode(error) ?? 0;
+    }
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    reset() {
+        this._state = 'closed';
+        this.consecutiveFailures = 0;
+        this.probeInFlight = false;
+        this.currentResetTimeoutMs = this.config.resetTimeoutMs;
+    }
+    /**
+     * Get diagnostic info for logging/monitoring.
+     */
+    getStatus() {
+        return {
+            state: this.state,
+            consecutiveFailures: this.consecutiveFailures,
+            currentResetTimeoutMs: this.currentResetTimeoutMs,
+            msSinceOpened: this.openedAt > 0 ? Date.now() - this.openedAt : null,
+        };
+    }
+    /**
+     * Create a CircuitOpenError with current diagnostic info.
+     */
+    createOpenError() {
+        const timeRemaining = Math.max(0, this.currentResetTimeoutMs - (Date.now() - this.openedAt));
+        return new CircuitOpenError(`Circuit breaker is open — Linear API calls blocked for ${Math.ceil(timeRemaining / 1000)}s. ` +
+            `${this.consecutiveFailures} consecutive auth failures detected.`, timeRemaining);
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    trip() {
+        this._state = 'open';
+        this.openedAt = Date.now();
+    }
+    shouldTransitionToHalfOpen() {
+        return Date.now() - this.openedAt >= this.currentResetTimeoutMs;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract HTTP status code from various error shapes
+ */
+function extractStatusCode(err) {
+    // Direct status/statusCode property
+    if (typeof err.status === 'number')
+        return err.status;
+    if (typeof err.statusCode === 'number')
+        return err.statusCode;
+    // Nested in response
+    const response = err.response;
+    if (response) {
+        if (typeof response.status === 'number')
+            return response.status;
+        if (typeof response.statusCode === 'number')
+            return response.statusCode;
+    }
+    return null;
+}
+/**
+ * Check if the error contains a Linear GraphQL RATELIMITED error code.
+ *
+ * Linear returns HTTP 200 with a GraphQL error body when rate-limited:
+ * { errors: [{ extensions: { code: 'RATELIMITED' } }] }
+ */
+function isGraphQLRateLimited(err) {
+    // Check error.extensions.code directly (Linear SDK error shape)
+    const extensions = err.extensions;
+    if (extensions?.code === 'RATELIMITED')
+        return true;
+    // Check nested errors array (raw GraphQL response shape)
+    const errors = err.errors;
+    if (Array.isArray(errors)) {
+        for (const gqlError of errors) {
+            const ext = gqlError.extensions;
+            if (ext?.code === 'RATELIMITED')
+                return true;
+        }
+    }
+    // Check response body for GraphQL errors
+    const response = err.response;
+    if (response) {
+        const body = response.body;
+        const data = response.data;
+        const target = body ?? data;
+        if (target) {
+            const bodyErrors = target.errors;
+            if (Array.isArray(bodyErrors)) {
+                for (const gqlError of bodyErrors) {
+                    const ext = gqlError.extensions;
+                    if (ext?.code === 'RATELIMITED')
+                        return true;
+                }
+            }
+        }
+    }
+    // Check error message as last resort
+    const message = err.message ?? '';
+    if (message.includes('RATELIMITED'))
+        return true;
+    return false;
+}

package/dist/src/circuit-breaker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=circuit-breaker.test.d.ts.map

package/dist/src/circuit-breaker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.test.d.ts","sourceRoot":"","sources":["../../src/circuit-breaker.test.ts"],"names":[],"mappings":""}

package/dist/src/circuit-breaker.test.js

@@ -0,0 +1,292 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { CircuitBreaker, DEFAULT_CIRCUIT_BREAKER_CONFIG } from './circuit-breaker.js';
+import { CircuitOpenError } from './errors.js';
+describe('CircuitBreaker', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    // ========================================================================
+    // Construction & defaults
+    // ========================================================================
+    it('starts in closed state', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.state).toBe('closed');
+    });
+    it('uses default config when none provided', () => {
+        const cb = new CircuitBreaker();
+        const status = cb.getStatus();
+        expect(status.state).toBe('closed');
+        expect(status.consecutiveFailures).toBe(0);
+        expect(status.currentResetTimeoutMs).toBe(DEFAULT_CIRCUIT_BREAKER_CONFIG.resetTimeoutMs);
+    });
+    it('accepts custom config', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 30_000 });
+        // Trip it 4 times — should still be closed
+        for (let i = 0; i < 4; i++) {
+            cb.recordAuthFailure(401);
+        }
+        expect(cb.state).toBe('closed');
+        // 5th failure trips it
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+    });
+    // ========================================================================
+    // canProceed
+    // ========================================================================
+    it('allows calls when closed', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.canProceed()).toBe(true);
+    });
+    it('blocks calls when open', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1 });
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        expect(cb.canProceed()).toBe(false);
+    });
+    it('allows one probe call when half-open', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1, resetTimeoutMs: 1000 });
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        // Advance past reset timeout
+        vi.advanceTimersByTime(1001);
+        expect(cb.state).toBe('half-open');
+        // First call should be allowed (probe)
+        expect(cb.canProceed()).toBe(true);
+        // Second call should be blocked (probe already in-flight)
+        expect(cb.canProceed()).toBe(false);
+    });
+    // ========================================================================
+    // State transitions: closed → open
+    // ========================================================================
+    it('trips after consecutive auth failures reach threshold', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 2 });
+        cb.recordAuthFailure(400);
+        expect(cb.state).toBe('closed');
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+    });
+    it('always counts failures regardless of status code (isAuthError already vetted)', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 2 });
+        cb.recordAuthFailure(200); // e.g., GraphQL 200 with auth error in body
+        expect(cb.getStatus().consecutiveFailures).toBe(1);
+        cb.recordAuthFailure(); // no status code at all
+        expect(cb.state).toBe('open');
+    });
+    it('resets failure count on success', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 3 });
+        cb.recordAuthFailure(401); // 1
+        cb.recordAuthFailure(403); // 2
+        cb.recordSuccess(); // reset to 0
+        cb.recordAuthFailure(400); // 1 — should NOT trip
+        expect(cb.state).toBe('closed');
+    });
+    // ========================================================================
+    // State transitions: open → half-open
+    // ========================================================================
+    it('transitions from open to half-open after resetTimeoutMs', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1, resetTimeoutMs: 5000 });
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        // Not enough time
+        vi.advanceTimersByTime(4999);
+        expect(cb.state).toBe('open');
+        // Exactly enough time
+        vi.advanceTimersByTime(1);
+        expect(cb.state).toBe('half-open');
+    });
+    // ========================================================================
+    // State transitions: half-open → closed (probe success)
+    // ========================================================================
+    it('closes circuit on successful probe in half-open', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1, resetTimeoutMs: 1000 });
+        cb.recordAuthFailure(401);
+        vi.advanceTimersByTime(1001);
+        expect(cb.state).toBe('half-open');
+        // Probe succeeds
+        cb.canProceed(); // acquire probe
+        cb.recordSuccess();
+        expect(cb.state).toBe('closed');
+        expect(cb.getStatus().consecutiveFailures).toBe(0);
+    });
+    // ========================================================================
+    // State transitions: half-open → open (probe failure + exponential backoff)
+    // ========================================================================
+    it('reopens circuit on failed probe with exponential backoff', () => {
+        const cb = new CircuitBreaker({
+            failureThreshold: 1,
+            resetTimeoutMs: 1000,
+            maxResetTimeoutMs: 16000,
+            backoffMultiplier: 2,
+        });
+        // First trip
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(1000);
+        // Wait for half-open
+        vi.advanceTimersByTime(1001);
+        expect(cb.state).toBe('half-open');
+        // Probe fails → reopen with backoff
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(2000); // 1000 * 2
+        // Wait 2000ms for next half-open
+        vi.advanceTimersByTime(2001);
+        expect(cb.state).toBe('half-open');
+        // Probe fails again → further backoff
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(4000); // 2000 * 2
+    });
+    it('caps reset timeout at maxResetTimeoutMs', () => {
+        const cb = new CircuitBreaker({
+            failureThreshold: 1,
+            resetTimeoutMs: 1000,
+            maxResetTimeoutMs: 3000,
+            backoffMultiplier: 2,
+        });
+        // Trip → open (1000ms)
+        cb.recordAuthFailure(401);
+        vi.advanceTimersByTime(1001);
+        // Probe fail → 2000ms
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        vi.advanceTimersByTime(2001);
+        // Probe fail → 3000ms (capped at max)
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(3000);
+        vi.advanceTimersByTime(3001);
+        // Probe fail → still 3000ms (capped)
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(3000);
+    });
+    it('resets backoff on successful recovery', () => {
+        const cb = new CircuitBreaker({
+            failureThreshold: 1,
+            resetTimeoutMs: 1000,
+            maxResetTimeoutMs: 16000,
+            backoffMultiplier: 2,
+        });
+        // Trip and backoff to 2000ms
+        cb.recordAuthFailure(401);
+        vi.advanceTimersByTime(1001);
+        cb.canProceed();
+        cb.recordAuthFailure(401);
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(2000);
+        // Recover
+        vi.advanceTimersByTime(2001);
+        cb.canProceed();
+        cb.recordSuccess();
+        expect(cb.state).toBe('closed');
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(1000); // reset to original
+    });
+    // ========================================================================
+    // reset()
+    // ========================================================================
+    it('reset() returns to closed from any state', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1 });
+        cb.recordAuthFailure(401);
+        expect(cb.state).toBe('open');
+        cb.reset();
+        expect(cb.state).toBe('closed');
+        expect(cb.getStatus().consecutiveFailures).toBe(0);
+        expect(cb.getStatus().currentResetTimeoutMs).toBe(DEFAULT_CIRCUIT_BREAKER_CONFIG.resetTimeoutMs);
+    });
+    // ========================================================================
+    // isAuthError
+    // ========================================================================
+    it('detects auth errors by HTTP status code', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.isAuthError({ status: 400 })).toBe(true);
+        expect(cb.isAuthError({ status: 401 })).toBe(true);
+        expect(cb.isAuthError({ status: 403 })).toBe(true);
+        expect(cb.isAuthError({ statusCode: 401 })).toBe(true);
+        expect(cb.isAuthError({ response: { status: 403 } })).toBe(true);
+    });
+    it('does not flag non-auth status codes', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.isAuthError({ status: 200 })).toBe(false);
+        expect(cb.isAuthError({ status: 404 })).toBe(false);
+        expect(cb.isAuthError({ status: 500 })).toBe(false);
+        expect(cb.isAuthError({ status: 429 })).toBe(false); // rate limit is handled separately
+    });
+    it('detects GraphQL RATELIMITED error code', () => {
+        const cb = new CircuitBreaker();
+        // Direct extensions.code
+        expect(cb.isAuthError({ extensions: { code: 'RATELIMITED' } })).toBe(true);
+        // Nested errors array
+        expect(cb.isAuthError({
+            errors: [{ extensions: { code: 'RATELIMITED' } }],
+        })).toBe(true);
+        // In response body
+        expect(cb.isAuthError({
+            response: {
+                body: {
+                    errors: [{ extensions: { code: 'RATELIMITED' } }],
+                },
+            },
+        })).toBe(true);
+        // In response data (alternative shape)
+        expect(cb.isAuthError({
+            response: {
+                data: {
+                    errors: [{ extensions: { code: 'RATELIMITED' } }],
+                },
+            },
+        })).toBe(true);
+    });
+    it('detects auth errors by message pattern', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.isAuthError({ message: 'Access denied - Only app users can create agent activities' })).toBe(true);
+        expect(cb.isAuthError({ message: 'Unauthorized request' })).toBe(true);
+        expect(cb.isAuthError({ message: 'Forbidden: insufficient permissions' })).toBe(true);
+    });
+    it('rejects non-error inputs', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.isAuthError(null)).toBe(false);
+        expect(cb.isAuthError(undefined)).toBe(false);
+        expect(cb.isAuthError('string')).toBe(false);
+        expect(cb.isAuthError(42)).toBe(false);
+    });
+    it('detects RATELIMITED in error message', () => {
+        const cb = new CircuitBreaker();
+        expect(cb.isAuthError({ message: 'GraphQL Error: RATELIMITED' })).toBe(true);
+    });
+    // ========================================================================
+    // createOpenError
+    // ========================================================================
+    it('creates a CircuitOpenError with remaining time info', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1, resetTimeoutMs: 10_000 });
+        cb.recordAuthFailure(401);
+        // 3 seconds have passed
+        vi.advanceTimersByTime(3000);
+        const error = cb.createOpenError();
+        expect(error).toBeInstanceOf(CircuitOpenError);
+        expect(error.code).toBe('CIRCUIT_OPEN');
+        expect(error.retryAfterMs).toBeGreaterThan(0);
+        expect(error.retryAfterMs).toBeLessThanOrEqual(7000);
+        expect(error.message).toMatch(/Circuit breaker is open/);
+    });
+    // ========================================================================
+    // getStatus diagnostic info
+    // ========================================================================
+    it('provides diagnostic status info', () => {
+        const cb = new CircuitBreaker({ failureThreshold: 1, resetTimeoutMs: 5000 });
+        let status = cb.getStatus();
+        expect(status.state).toBe('closed');
+        expect(status.consecutiveFailures).toBe(0);
+        expect(status.msSinceOpened).toBeNull();
+        cb.recordAuthFailure(401);
+        vi.advanceTimersByTime(2000);
+        status = cb.getStatus();
+        expect(status.state).toBe('open');
+        expect(status.consecutiveFailures).toBe(1);
+        expect(status.msSinceOpened).toBeGreaterThanOrEqual(2000);
+    });
+});

package/dist/src/errors.d.ts

@@ -54,6 +54,14 @@ export declare class LinearStatusTransitionError extends LinearAgentError {
     readonly toStatus: string;
     constructor(message: string, issueId: string, fromStatus: string, toStatus: string);
 }
+/**
+ * Error thrown when the circuit breaker is open.
+ * All API calls are blocked to prevent wasting rate limit quota.
+ */
+export declare class CircuitOpenError extends LinearAgentError {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
 /**
  * Error thrown when agent spawning fails
  */
@@ -72,6 +80,10 @@ export declare function isLinearAgentError(error: unknown): error is LinearAgent
  * Type guard to check if an error is an AgentSpawnError
  */
 export declare function isAgentSpawnError(error: unknown): error is AgentSpawnError;
+/**
+ * Type guard to check if an error is a CircuitOpenError
+ */
+export declare function isCircuitOpenError(error: unknown): error is CircuitOpenError;
 /**
  * Type guard to check if an error is retryable
  */

package/dist/src/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAQpD;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,gBAAgB;aAGhC,UAAU,EAAE,MAAM;aAClB,QAAQ,CAAC,EAAE,OAAO;gBAFlC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,OAAO,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,gBAAgB;aAG3C,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,KAAK;gBAFhC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,KAAK;CAQnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;aAGpC,SAAS,CAAC,EAAE,MAAM;aAClB,OAAO,CAAC,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;aAGrC,YAAY,EAAE,MAAM;aACpB,SAAS,CAAC,EAAE,MAAM;gBAFlC,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;aACN,SAAS,CAAC,EAAE,MAAM;gBAAnD,OAAO,EAAE,MAAM,EAAkB,SAAS,CAAC,EAAE,MAAM,YAAA;CAIhE;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,gBAAgB;aAG7C,OAAO,EAAE,MAAM;aACf,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,MAAM;gBAHhC,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM;CASnC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;aAGjC,OAAO,EAAE,MAAM;aACf,SAAS,CAAC,EAAE,MAAM;aAClB,WAAW,EAAE,OAAO;aACpB,KAAK,CAAC,EAAE,KAAK;gBAJ7B,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,WAAW,GAAE,OAAe,EAC5B,KAAK,CAAC,EAAE,KAAK,YAAA;CAUhC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,oBAAoB,GAAE,MAAM,EAA8B,GACzD,OAAO,CAkBT"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAQpD;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,gBAAgB;aAGhC,UAAU,EAAE,MAAM;aAClB,QAAQ,CAAC,EAAE,OAAO;gBAFlC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,OAAO,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,gBAAgB;aAG3C,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,KAAK;gBAFhC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,KAAK;CAQnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;aAGpC,SAAS,CAAC,EAAE,MAAM;aAClB,OAAO,CAAC,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;aAGrC,YAAY,EAAE,MAAM;aACpB,SAAS,CAAC,EAAE,MAAM;gBAFlC,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;aACN,SAAS,CAAC,EAAE,MAAM;gBAAnD,OAAO,EAAE,MAAM,EAAkB,SAAS,CAAC,EAAE,MAAM,YAAA;CAIhE;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,gBAAgB;aAG7C,OAAO,EAAE,MAAM;aACf,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,MAAM;gBAHhC,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM;CASnC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,gBAAgB;aAGlC,YAAY,EAAE,MAAM;gBADpC,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,MAAM;CAKvC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;aAGjC,OAAO,EAAE,MAAM;aACf,SAAS,CAAC,EAAE,MAAM;aAClB,WAAW,EAAE,OAAO;aACpB,KAAK,CAAC,EAAE,KAAK;gBAJ7B,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,WAAW,GAAE,OAAe,EAC5B,KAAK,CAAC,EAAE,KAAK,YAAA;CAUhC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,oBAAoB,GAAE,MAAM,EAA8B,GACzD,OAAO,CAkBT"}

package/dist/src/errors.js

@@ -99,6 +99,18 @@ export class LinearStatusTransitionError extends LinearAgentError {
         this.name = 'LinearStatusTransitionError';
     }
 }
+/**
+ * Error thrown when the circuit breaker is open.
+ * All API calls are blocked to prevent wasting rate limit quota.
+ */
+export class CircuitOpenError extends LinearAgentError {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message, 'CIRCUIT_OPEN', { retryAfterMs });
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'CircuitOpenError';
+    }
+}
 /**
  * Error thrown when agent spawning fails
  */
@@ -133,6 +145,12 @@ export function isLinearAgentError(error) {
 export function isAgentSpawnError(error) {
     return error instanceof AgentSpawnError;
 }
+/**
+ * Type guard to check if an error is a CircuitOpenError
+ */
+export function isCircuitOpenError(error) {
+    return error instanceof CircuitOpenError;
+}
 /**
  * Type guard to check if an error is retryable
  */