@supaku/agentfactory-linear 0.7.18 → 0.7.19

package/dist/src/agent-client-project-repo.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { LinearAgentClient } from './agent-client.js';
 import { TokenBucket } from './rate-limiter.js';
+import { CircuitBreaker } from './circuit-breaker.js';
 // ---------------------------------------------------------------------------
 // Mock helpers
 // ---------------------------------------------------------------------------
@@ -30,6 +31,7 @@ function createClientWithProject(project) {
         writable: false,
     });
     Object.defineProperty(client, 'rateLimiter', { value: new TokenBucket(), writable: false });
+    Object.defineProperty(client, 'circuitBreaker', { value: new CircuitBreaker(), writable: false });
     Object.defineProperty(client, 'statusCache', { value: new Map(), writable: false });
     return client;
 }

package/dist/src/agent-client.d.ts

@@ -9,6 +9,7 @@ export declare class LinearAgentClient {
     private readonly client;
     private readonly retryConfig;
     private readonly rateLimiter;
+    private readonly circuitBreaker;
     private statusCache;
     constructor(config: LinearAgentClientConfig);
     /**
@@ -16,11 +17,15 @@ export declare class LinearAgentClient {
      */
     get linearClient(): LinearClient;
     /**
-     * Execute an operation with retry logic and rate limiting.
+     * Execute an operation with circuit breaker, rate limiting, and retry logic.
      *
-     * On HTTP 429 (rate limited):
-     * - Uses the Retry-After header value for the wait delay (falls back to 60s)
-     * - Penalizes the token bucket so concurrent callers also back off
+     * Order of operations:
+     * 1. Check circuit breaker — if open, throw CircuitOpenError (zero quota consumed)
+     * 2. Acquire rate limit token
+     * 3. Execute the operation
+     * 4. On success: record success on circuit breaker
+     * 5. On auth error: record failure on circuit breaker (may trip it)
+     * 6. On retryable error: retry with exponential backoff
      */
     private withRetry;
     /**

package/dist/src/agent-client.d.ts.map

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

package/dist/src/agent-client.js

@@ -2,6 +2,7 @@ import { LinearClient, AgentActivitySignal as LinearAgentActivitySignal, IssueRe
 import { LinearApiError, LinearStatusTransitionError } from './errors.js';
 import { withRetry, DEFAULT_RETRY_CONFIG } from './retry.js';
 import { TokenBucket, extractRetryAfterMs } from './rate-limiter.js';
+import { CircuitBreaker } from './circuit-breaker.js';
 /**
  * Core Linear Agent Client
  * Wraps @linear/sdk with retry logic and helper methods
@@ -10,6 +11,7 @@ export class LinearAgentClient {
     client;
     retryConfig;
     rateLimiter;
+    circuitBreaker;
     statusCache = new Map();
     constructor(config) {
         this.client = new LinearClient({
@@ -20,7 +22,8 @@ export class LinearAgentClient {
             ...DEFAULT_RETRY_CONFIG,
             ...config.retry,
         };
-        this.rateLimiter = new TokenBucket(config.rateLimit);
+        this.rateLimiter = config.rateLimiterStrategy ?? new TokenBucket(config.rateLimit);
+        this.circuitBreaker = config.circuitBreakerStrategy ?? new CircuitBreaker(config.circuitBreaker);
     }
     /**
      * Get the underlying LinearClient instance
@@ -29,16 +32,44 @@ export class LinearAgentClient {
         return this.client;
     }
     /**
-     * Execute an operation with retry logic and rate limiting.
+     * Execute an operation with circuit breaker, rate limiting, and retry logic.
      *
-     * On HTTP 429 (rate limited):
-     * - Uses the Retry-After header value for the wait delay (falls back to 60s)
-     * - Penalizes the token bucket so concurrent callers also back off
+     * Order of operations:
+     * 1. Check circuit breaker — if open, throw CircuitOpenError (zero quota consumed)
+     * 2. Acquire rate limit token
+     * 3. Execute the operation
+     * 4. On success: record success on circuit breaker
+     * 5. On auth error: record failure on circuit breaker (may trip it)
+     * 6. On retryable error: retry with exponential backoff
      */
     async withRetry(fn) {
         return withRetry(async () => {
+            // Check circuit breaker BEFORE acquiring a rate limit token
+            const canProceed = await this.circuitBreaker.canProceed();
+            if (!canProceed) {
+                // Create a descriptive error; if the breaker is a CircuitBreaker instance, use its helper
+                const breaker = this.circuitBreaker;
+                if (typeof breaker.createOpenError === 'function') {
+                    throw breaker.createOpenError();
+                }
+                throw new LinearApiError('Circuit breaker is open — API calls blocked', 503);
+            }
             await this.rateLimiter.acquire();
-            return fn();
+            try {
+                const result = await fn();
+                // Record success to close/reset the circuit
+                await this.circuitBreaker.recordSuccess();
+                return result;
+            }
+            catch (error) {
+                // Check if this is an auth error that should trip the circuit
+                if (this.circuitBreaker.isAuthError(error)) {
+                    const statusCode = extractAuthStatusCode(error);
+                    await this.circuitBreaker.recordAuthFailure(statusCode);
+                    console.warn(`[LinearAgentClient] Auth error detected (status ${statusCode}), circuit breaker notified`);
+                }
+                throw error;
+            }
         }, {
             config: this.retryConfig,
             getRetryAfterMs: extractRetryAfterMs,
@@ -448,6 +479,15 @@ export class LinearAgentClient {
      * @returns Array of issue data with childCount for parent detection
      */
     async listProjectIssues(project) {
+        // Check circuit breaker before consuming rate limit token
+        const canProceed = await this.circuitBreaker.canProceed();
+        if (!canProceed) {
+            const breaker = this.circuitBreaker;
+            if (typeof breaker.createOpenError === 'function') {
+                throw breaker.createOpenError();
+            }
+            throw new LinearApiError('Circuit breaker is open — API calls blocked', 503);
+        }
         await this.rateLimiter.acquire();
         const query = `
       query ListProjectIssues($filter: IssueFilter!) {
@@ -468,25 +508,36 @@ export class LinearAgentClient {
       }
     `;
         const terminalStatuses = ['Accepted', 'Canceled', 'Duplicate'];
-        const result = await this.client.client.rawRequest(query, {
-            filter: {
-                project: { name: { eq: project } },
-                state: { name: { nin: terminalStatuses } },
-            },
-        });
-        const data = result.data;
-        return data.issues.nodes.map((node) => ({
-            id: node.id,
-            identifier: node.identifier,
-            title: node.title,
-            description: node.description ?? undefined,
-            status: node.state?.name ?? 'Backlog',
-            labels: node.labels.nodes.map((l) => l.name),
-            createdAt: new Date(node.createdAt).getTime(),
-            parentId: node.parent?.id ?? undefined,
-            project: node.project?.name ?? undefined,
-            childCount: node.children.nodes.length,
-        }));
+        try {
+            const result = await this.client.client.rawRequest(query, {
+                filter: {
+                    project: { name: { eq: project } },
+                    state: { name: { nin: terminalStatuses } },
+                },
+            });
+            // Record success on circuit breaker
+            await this.circuitBreaker.recordSuccess();
+            const data = result.data;
+            return data.issues.nodes.map((node) => ({
+                id: node.id,
+                identifier: node.identifier,
+                title: node.title,
+                description: node.description ?? undefined,
+                status: node.state?.name ?? 'Backlog',
+                labels: node.labels.nodes.map((l) => l.name),
+                createdAt: new Date(node.createdAt).getTime(),
+                parentId: node.parent?.id ?? undefined,
+                project: node.project?.name ?? undefined,
+                childCount: node.children.nodes.length,
+            }));
+        }
+        catch (error) {
+            if (this.circuitBreaker.isAuthError(error)) {
+                const statusCode = extractAuthStatusCode(error);
+                await this.circuitBreaker.recordAuthFailure(statusCode);
+            }
+            throw error;
+        }
     }
     /**
      * Check if an issue has child issues (is a parent issue)
@@ -642,3 +693,27 @@ export class LinearAgentClient {
 export function createLinearAgentClient(config) {
     return new LinearAgentClient(config);
 }
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract HTTP status code from an error for circuit breaker recording.
+ */
+function extractAuthStatusCode(error) {
+    if (typeof error !== 'object' || error === null)
+        return 0;
+    const err = error;
+    if (typeof err.status === 'number')
+        return err.status;
+    if (typeof err.statusCode === 'number')
+        return err.statusCode;
+    const response = err.response;
+    if (response) {
+        if (typeof response.status === 'number')
+            return response.status;
+        if (typeof response.statusCode === 'number')
+            return response.statusCode;
+    }
+    // Default to 400 for auth errors detected by message pattern
+    return 400;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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.
+     */
+    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;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAwB3C;;;;;;;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,231 @@
+/**
+ * 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.
+     */
+    recordAuthFailure(statusCode) {
+        this.probeInFlight = false;
+        if (!this.config.authErrorCodes.includes(statusCode)) {
+            return;
+        }
+        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":""}