pi-smart-router 0.1.0

package/dist/infrastructure/gateway/circuit-breaker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Circuit breaker for gateway dispatch — T055, FR-018, FR-022.
+ *
+ * Tracks consecutive infrastructure failures per model endpoint and trips
+ * the breaker when the threshold is exceeded. Only infra errors (timeouts,
+ * network failures, 5xx) count — policy/safety rejections (4xx content
+ * filtering, 403 auth) do NOT trigger the breaker (FR-018).
+ *
+ * States: CLOSED → OPEN → HALF_OPEN → CLOSED (on success) or OPEN (on fail).
+ */
+export type CircuitState = 'closed' | 'open' | 'half_open';
+export interface CircuitBreakerConfig {
+    /** Consecutive infra failures before tripping the breaker. */
+    readonly failureThreshold: number;
+    /** Milliseconds to remain in OPEN state before allowing a probe. */
+    readonly resetTimeoutMs: number;
+    /** Max consecutive successes in HALF_OPEN required to close. */
+    readonly halfOpenSuccesses: number;
+}
+export declare const DEFAULT_CIRCUIT_CONFIG: CircuitBreakerConfig;
+export interface CircuitSnapshot {
+    readonly modelId: string;
+    readonly state: CircuitState;
+    readonly consecutiveFailures: number;
+    readonly consecutiveSuccesses: number;
+    readonly lastFailureAt: number | null;
+    readonly lastStateChangeAt: number;
+}
+/**
+ * Returns true when the error is an infrastructure failure that should
+ * trigger the circuit breaker. Policy/safety rejections are excluded
+ * per FR-018.
+ */
+export declare function isInfraError(error: {
+    statusCode?: number;
+    code?: string;
+    message?: string;
+}): boolean;
+export declare class CircuitBreaker {
+    private readonly circuits;
+    private readonly config;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Check whether a model endpoint is available for requests.
+     * OPEN circuits reject immediately. OPEN circuits whose reset timeout
+     * has elapsed transition to HALF_OPEN and allow a probe.
+     */
+    canDispatch(modelId: string): boolean;
+    /**
+     * Record a successful response from a model endpoint.
+     * In HALF_OPEN, accumulates successes until the threshold is met,
+     * then transitions to CLOSED. In CLOSED, resets the failure counter.
+     */
+    recordSuccess(modelId: string): void;
+    /**
+     * Record an infrastructure failure from a model endpoint.
+     * Only infra errors should be reported here (caller checks isInfraError).
+     * HALF_OPEN → OPEN immediately. CLOSED → OPEN when threshold exceeded.
+     */
+    recordFailure(modelId: string): void;
+    /** Get a read-only snapshot of a model's circuit state. */
+    getSnapshot(modelId: string): CircuitSnapshot;
+    /** Reset a specific model's circuit to CLOSED. */
+    reset(modelId: string): void;
+    /** List all model IDs with OPEN circuits (unhealthy endpoints). */
+    getOpenCircuits(): readonly string[];
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/infrastructure/gateway/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/gateway/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,eAAO,MAAM,sBAAsB,EAAE,oBAIpC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAUD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAcrG;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;gBAElC,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAItD;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAmBrC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAiBpC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IA+BpC,2DAA2D;IAC3D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe;IAuB7C,kDAAkD;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,mEAAmE;IACnE,eAAe,IAAI,SAAS,MAAM,EAAE;CASrC"}

package/dist/infrastructure/gateway/circuit-breaker.js

@@ -0,0 +1,150 @@
+/**
+ * Circuit breaker for gateway dispatch — T055, FR-018, FR-022.
+ *
+ * Tracks consecutive infrastructure failures per model endpoint and trips
+ * the breaker when the threshold is exceeded. Only infra errors (timeouts,
+ * network failures, 5xx) count — policy/safety rejections (4xx content
+ * filtering, 403 auth) do NOT trigger the breaker (FR-018).
+ *
+ * States: CLOSED → OPEN → HALF_OPEN → CLOSED (on success) or OPEN (on fail).
+ */
+export const DEFAULT_CIRCUIT_CONFIG = {
+    failureThreshold: 3,
+    resetTimeoutMs: 30_000,
+    halfOpenSuccesses: 2,
+};
+/**
+ * Returns true when the error is an infrastructure failure that should
+ * trigger the circuit breaker. Policy/safety rejections are excluded
+ * per FR-018.
+ */
+export function isInfraError(error) {
+    if (error.code === 'ECONNREFUSED' || error.code === 'ECONNRESET' ||
+        error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND' ||
+        error.code === 'UND_ERR_CONNECT_TIMEOUT' || error.code === 'UND_ERR_SOCKET') {
+        return true;
+    }
+    if (error.statusCode !== undefined) {
+        if (error.statusCode >= 500 || error.statusCode === 429) {
+            return true;
+        }
+    }
+    return false;
+}
+export class CircuitBreaker {
+    circuits = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CIRCUIT_CONFIG, ...config };
+    }
+    /**
+     * Check whether a model endpoint is available for requests.
+     * OPEN circuits reject immediately. OPEN circuits whose reset timeout
+     * has elapsed transition to HALF_OPEN and allow a probe.
+     */
+    canDispatch(modelId) {
+        const entry = this.circuits.get(modelId);
+        if (!entry)
+            return true;
+        if (entry.state === 'closed' || entry.state === 'half_open') {
+            return true;
+        }
+        const elapsed = Date.now() - entry.lastStateChangeAt;
+        if (elapsed >= this.config.resetTimeoutMs) {
+            entry.state = 'half_open';
+            entry.consecutiveSuccesses = 0;
+            entry.lastStateChangeAt = Date.now();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Record a successful response from a model endpoint.
+     * In HALF_OPEN, accumulates successes until the threshold is met,
+     * then transitions to CLOSED. In CLOSED, resets the failure counter.
+     */
+    recordSuccess(modelId) {
+        const entry = this.circuits.get(modelId);
+        if (!entry)
+            return;
+        entry.consecutiveFailures = 0;
+        if (entry.state === 'half_open') {
+            entry.consecutiveSuccesses += 1;
+            if (entry.consecutiveSuccesses >= this.config.halfOpenSuccesses) {
+                entry.state = 'closed';
+                entry.lastStateChangeAt = Date.now();
+            }
+        }
+        else if (entry.state === 'closed') {
+            entry.consecutiveSuccesses = 0;
+        }
+    }
+    /**
+     * Record an infrastructure failure from a model endpoint.
+     * Only infra errors should be reported here (caller checks isInfraError).
+     * HALF_OPEN → OPEN immediately. CLOSED → OPEN when threshold exceeded.
+     */
+    recordFailure(modelId) {
+        const now = Date.now();
+        let entry = this.circuits.get(modelId);
+        if (!entry) {
+            entry = {
+                state: 'closed',
+                consecutiveFailures: 0,
+                consecutiveSuccesses: 0,
+                lastFailureAt: null,
+                lastStateChangeAt: now,
+            };
+            this.circuits.set(modelId, entry);
+        }
+        entry.consecutiveFailures += 1;
+        entry.lastFailureAt = now;
+        entry.consecutiveSuccesses = 0;
+        if (entry.state === 'half_open') {
+            entry.state = 'open';
+            entry.lastStateChangeAt = now;
+            return;
+        }
+        if (entry.consecutiveFailures >= this.config.failureThreshold) {
+            entry.state = 'open';
+            entry.lastStateChangeAt = now;
+        }
+    }
+    /** Get a read-only snapshot of a model's circuit state. */
+    getSnapshot(modelId) {
+        const entry = this.circuits.get(modelId);
+        if (!entry) {
+            return {
+                modelId,
+                state: 'closed',
+                consecutiveFailures: 0,
+                consecutiveSuccesses: 0,
+                lastFailureAt: null,
+                lastStateChangeAt: 0,
+            };
+        }
+        return {
+            modelId,
+            state: entry.state,
+            consecutiveFailures: entry.consecutiveFailures,
+            consecutiveSuccesses: entry.consecutiveSuccesses,
+            lastFailureAt: entry.lastFailureAt,
+            lastStateChangeAt: entry.lastStateChangeAt,
+        };
+    }
+    /** Reset a specific model's circuit to CLOSED. */
+    reset(modelId) {
+        this.circuits.delete(modelId);
+    }
+    /** List all model IDs with OPEN circuits (unhealthy endpoints). */
+    getOpenCircuits() {
+        const open = [];
+        for (const [modelId, entry] of this.circuits) {
+            if (entry.state === 'open') {
+                open.push(modelId);
+            }
+        }
+        return open;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/infrastructure/gateway/circuit-breaker.js.map

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

package/dist/infrastructure/gateway/gateway-dispatch.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Gateway dispatch — T020, T055, T056, FR-001, FR-017, FR-018, FR-022, FR-023.
+ *
+ * Infrastructure entry point that delegates routing to the domain pipeline.
+ * Integrates circuit breaker for resilient failover (FR-018: infra errors only),
+ * weighted distribution across same-tier model endpoints (T056), and
+ * per-key rate limiting with 429 + Retry-After responses (T057, FR-017).
+ *
+ * FR-023: preserves provider context-caching semantics on same-provider
+ * request paths by tracking the last-used provider per session.
+ *
+ * SP-097: Cursor subscription quota exhaustion detection and failover to
+ * `cursor/auto` or economical API models with `cursor_quota_exhausted` telemetry.
+ */
+import type { ModelProfile, RoutingDecision, RoutingRequest } from '../../domain/types/index.js';
+import type { PipelineOptions } from '../../domain/pipeline/router-pipeline.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import type { CircuitBreakerConfig } from './circuit-breaker.js';
+export interface CacheMarker {
+    readonly sessionId: string;
+    readonly provider: string;
+    readonly modelId: string;
+    readonly cacheFriendly: boolean;
+}
+export interface RateLimitResult {
+    readonly limited: true;
+    readonly error: 'rate_limit_exceeded';
+    /** Seconds until the bucket refills enough for the next request. */
+    readonly retry_after_seconds: number;
+}
+export interface RateLimitPort {
+    /** Attempt to consume a token for the given key. */
+    consumeToken(key: string, cost?: number): {
+        allowed: boolean;
+        remaining: number;
+        retryAfterSeconds: number | null;
+    };
+}
+export interface ProviderErrorShape {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly message?: string;
+}
+/**
+ * Classify Cursor subscription quota / usage-limit errors from dogfood evidence
+ * (#70: "You've hit your usage limit… Switch to Auto for more usage…").
+ */
+export declare function isCursorQuotaExhaustedError(error: ProviderErrorShape): boolean;
+/** Cursor frontier models billed against subscription quota (composer-*, cursor/*). */
+export declare function isCursorSubscriptionModel(model: ModelProfile): boolean;
+/** Cursor opaque-auto models (`cursor/auto`, `cursor/*`). */
+export declare function isCursorAutoModel(model: ModelProfile): boolean;
+/**
+ * Whether a provider error should trigger model failover (infra or Cursor quota).
+ * Quota exhaustion on Cursor subscription models must not trip the circuit breaker.
+ */
+export declare function shouldFailoverOnProviderError(error: ProviderErrorShape, failedModel?: ModelProfile): boolean;
+export interface GatewayDispatchOptions extends PipelineOptions {
+    readonly circuitBreakerConfig?: Partial<CircuitBreakerConfig>;
+    readonly rateLimiter?: RateLimitPort;
+}
+export interface GatewayDispatchRequestOptions {
+    readonly effectiveFleet?: readonly ModelProfile[];
+}
+/**
+ * Select a model from same-tier candidates using inverse-cost weighting.
+ * Models with lower cost get proportionally more traffic. Falls back to
+ * uniform random when all costs are equal.
+ */
+export declare function weightedSelect(candidates: readonly ModelProfile[]): ModelProfile | undefined;
+export declare class GatewayDispatch {
+    private readonly pipeline;
+    private readonly fleet;
+    private readonly cacheMarkers;
+    private readonly circuitBreaker;
+    private readonly rateLimiter;
+    private readonly quotaExhaustedModels;
+    constructor(fleet: readonly ModelProfile[], options?: GatewayDispatchOptions);
+    /**
+     * Route a single request through the pipeline.
+     *
+     * 1. Run pipeline to get routing decision.
+     * 2. Verify circuit breaker allows dispatch to the selected model.
+     * 3. If the selected model's circuit is open, attempt failover to a
+     *    same-tier alternative (T056).
+     * 4. Update FR-023 cache marker.
+     *
+     * Never throws.
+     */
+    dispatch(request: RoutingRequest, options?: GatewayDispatchRequestOptions): Promise<RoutingDecision>;
+    /**
+     * Route with per-key rate limiting (T057, FR-017).
+     *
+     * Checks the token bucket before routing. Returns a RateLimitResult with
+     * 429-compatible body `{ error, retry_after_seconds }` when the bucket is
+     * exhausted. Otherwise delegates to dispatch().
+     */
+    dispatchWithRateLimit(request: RoutingRequest, rateLimitKey: string): Promise<RoutingDecision | RateLimitResult>;
+    /**
+     * Record an upstream response outcome for circuit breaker tracking.
+     * Only infra errors trip the breaker; policy/safety rejections are ignored (FR-018).
+     * Cursor quota exhaustion is tracked for SP-097 failover without opening circuits.
+     */
+    recordOutcome(modelId: string, error?: ProviderErrorShape): void;
+    /** Expose circuit breaker for observability and testing. */
+    getCircuitBreaker(): CircuitBreaker;
+    /** Whether a model recently returned a Cursor quota exhaustion error (SP-097). */
+    hasQuotaExhaustion(modelId: string): boolean;
+    /**
+     * Retrieve the current cache marker for a session (FR-023 inspection).
+     */
+    getCacheMarker(sessionId: string): CacheMarker | null;
+    /**
+     * Select an alternate model when the current target is unavailable or failed.
+     * Prefers same-tier healthy models with closed circuits, then any tier.
+     * When the failed model hit Cursor quota limits, prefers `cursor/auto` then
+     * economical API models with `cursor_quota_exhausted`.
+     */
+    selectFailover(decision: RoutingDecision, excludeModelIds?: readonly string[], fleetOverride?: readonly ModelProfile[]): RoutingDecision | undefined;
+    /**
+     * If the selected model's circuit is open, attempt to fail over to
+     * an alternative model on the same tier (T056 weighted distribution).
+     * Falls back to any healthy model on any tier if no same-tier alternative exists.
+     */
+    private applyCircuitBreaker;
+    /**
+     * SP-097: fail over from quota-exhausted Cursor models to `cursor/auto` or
+     * the cheapest viable economical API model in the scoped fleet.
+     */
+    private selectCursorQuotaFailover;
+    /**
+     * FR-023: track the provider and cache-friendly status for the session.
+     * Sub-routed requests on the same provider preserve the existing marker
+     * rather than replacing it — the pin model's cache state is authoritative.
+     */
+    private updateCacheMarker;
+}
+//# sourceMappingURL=gateway-dispatch.d.ts.map

package/dist/infrastructure/gateway/gateway-dispatch.d.ts.map

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