@driftgard/node 1.5.0 → 1.6.0

package/README.md

@@ -51,7 +51,6 @@ const result = await dg.evaluate({
 ```
 
 This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard.
-```
 
 ## A/B experiments
 
@@ -89,11 +88,28 @@ const result = await dg.evaluate({
 ```
 
 All fields in `usage` are optional. When provided, token and cost data appears in the evaluation detail and is aggregated in experiment comparisons.
+
+## Cost alerts
+
+When cost alerting is enabled on your project, the response includes a `cost_alert` field if a threshold is exceeded:
+
+```typescript
+const result = await dg.evaluate({ ... });
+
+if (result.cost_alert) {
+  console.warn(`Cost alert: ${result.cost_alert.scope} spend $${result.cost_alert.actual_usd} exceeds $${result.cost_alert.threshold_usd}`);
+  // Throttle the agent, notify the user, etc.
+}
 ```
 
+Configure thresholds in Settings — per-project, per-model, or per-session. Session-scoped alerts catch runaway agent loops in real-time.
+
 ## Features
 
 - Single `evaluate()` method — send prompt/response, get verdict
+- Failure mode: `fail-open` or `fail-closed` when API is unreachable
+- Circuit breaker: skips API after consecutive failures, auto-recovers
+- Idempotency: deduplicates retried requests via `x-idempotency-key`
 - Auto-retry with exponential backoff on 5xx and network errors
 - Typed errors: `AuthError`, `RateLimitError`, `FeatureNotAvailableError`, `ChainDepthExceededError`
 - Full TypeScript types for requests and responses
@@ -107,9 +123,35 @@ const dg = new Driftgard({
   baseUrl: "https://api.driftgard.com", // optional
   timeout: 30000,               // optional, ms (default 30s)
   maxRetries: 2,                // optional (default 2)
+  failureMode: "open",         // "open" = allow if API down, "closed" = block (default "open")
+  circuitBreaker: {
+    threshold: 5,               // open circuit after 5 consecutive failures (default 5)
+    resetTimeoutMs: 30000,      // try again after 30s (default 30000)
+  },
 });
 ```
 
+## Failure mode & circuit breaker
+
+The SDK never throws on network/server errors during `evaluate()`. Instead, it returns a synthetic response:
+
+```typescript
+const result = await dg.evaluate({ ... });
+
+// Check where the decision came from
+console.log(result.decision_source);
+// "policy"           — normal API evaluation
+// "failure_mode"     — API unreachable, failureMode applied
+// "circuit_open"     — circuit breaker open, failureMode applied
+// "idempotency_cache" — duplicate request, cached result returned
+
+// Monitor circuit breaker state
+console.log(dg.circuitBreakerState);
+// { state: "closed", failures: 0, openedAt: 0 }
+```
+
+With `failureMode: "open"` (default), the SDK allows requests through when Driftgard is unavailable. With `failureMode: "closed"`, it blocks them with a fallback message.
+
 ## Error handling
 
 ```typescript

package/dist/index.d.ts

@@ -1,17 +1,34 @@
 import { DriftgardConfig, EvaluateRequest, EvaluateResponse } from "./types";
-export { DriftgardConfig, EvaluateRequest, EvaluateResponse } from "./types";
+export { DriftgardConfig, EvaluateRequest, EvaluateResponse, CircuitBreakerConfig } from "./types";
 export { Violation, EvaluationResult, FallbackResponse, HitlInfo } from "./types";
 export { DriftgardError, AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError } from "./errors";
+type CircuitState = "closed" | "open" | "half-open";
 export declare class Driftgard {
     private apiKey;
     private baseUrl;
     private timeout;
     private maxRetries;
+    private failureMode;
+    private cbThreshold;
+    private cbResetMs;
+    private cbState;
+    private cbFailures;
+    private cbOpenedAt;
     constructor(config: DriftgardConfig);
     /**
      * Evaluate a prompt/response pair against your active control pack.
+     * Handles circuit breaker and failure mode automatically.
      */
     evaluate(req: EvaluateRequest): Promise<EvaluateResponse>;
+    /** Generate a synthetic response based on failure mode. */
+    private syntheticResponse;
+    /** Get current circuit breaker state (for observability). */
+    get circuitBreakerState(): {
+        state: CircuitState;
+        failures: number;
+        openedAt: number;
+    };
+    private generateIdempotencyKey;
     private post;
     private delay;
 }

package/dist/index.js

@@ -12,35 +12,119 @@ const DEFAULT_BASE_URL = "https://api.driftgard.com";
 const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_MAX_RETRIES = 2;
 const RETRY_DELAY_MS = 500;
+const DEFAULT_CB_THRESHOLD = 5;
+const DEFAULT_CB_RESET_MS = 30000;
 class Driftgard {
     constructor(config) {
+        this.cbState = "closed";
+        this.cbFailures = 0;
+        this.cbOpenedAt = 0;
         if (!config.apiKey)
             throw new Error("apiKey is required");
         this.apiKey = config.apiKey;
         this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
         this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.failureMode = config.failureMode ?? "open";
+        this.cbThreshold = config.circuitBreaker?.threshold ?? DEFAULT_CB_THRESHOLD;
+        this.cbResetMs = config.circuitBreaker?.resetTimeoutMs ?? DEFAULT_CB_RESET_MS;
     }
     /**
      * Evaluate a prompt/response pair against your active control pack.
+     * Handles circuit breaker and failure mode automatically.
      */
     async evaluate(req) {
-        return this.post("/audit/evaluate", {
+        const idempotencyKey = req.idempotency_key || this.generateIdempotencyKey();
+        // Circuit breaker: if open, check if reset timeout has passed
+        if (this.cbState === "open") {
+            if (Date.now() - this.cbOpenedAt >= this.cbResetMs) {
+                this.cbState = "half-open";
+            }
+            else {
+                // Circuit is open — apply failure mode without calling API
+                return this.syntheticResponse(req, "circuit_open");
+            }
+        }
+        try {
+            const result = await this.post("/audit/evaluate", {
+                project_id: req.project_id,
+                prompt: req.prompt,
+                response: req.response,
+                model_id: req.model_id,
+                timestamp: req.timestamp || new Date().toISOString(),
+                ...(req.experiment_id ? { experiment_id: req.experiment_id } : {}),
+                ...(req.session_id ? { session_id: req.session_id } : {}),
+                ...(req.parent_evaluation_id ? { parent_evaluation_id: req.parent_evaluation_id } : {}),
+                ...(req.control_pack_id ? { control_pack_id: req.control_pack_id } : {}),
+                ...(req.control_pack_version ? { control_pack_version: req.control_pack_version } : {}),
+                ...(req.dry_run ? { dry_run: req.dry_run } : {}),
+                ...(req.usage ? { usage: req.usage } : {}),
+            }, idempotencyKey);
+            // Success — reset circuit breaker
+            this.cbFailures = 0;
+            this.cbState = "closed";
+            return result;
+        }
+        catch (e) {
+            // Auth, rate limit, chain depth, feature errors are real errors — don't trigger circuit breaker
+            if (e instanceof errors_1.AuthError || e instanceof errors_1.RateLimitError ||
+                e instanceof errors_1.ChainDepthExceededError || e instanceof errors_1.FeatureNotAvailableError) {
+                throw e;
+            }
+            // Network/server error — increment circuit breaker
+            this.cbFailures++;
+            if (this.cbFailures >= this.cbThreshold) {
+                this.cbState = "open";
+                this.cbOpenedAt = Date.now();
+            }
+            // Apply failure mode
+            return this.syntheticResponse(req, "failure_mode");
+        }
+    }
+    /** Generate a synthetic response based on failure mode. */
+    syntheticResponse(req, source) {
+        const allowed = this.failureMode === "open";
+        return {
+            ok: true,
             project_id: req.project_id,
-            prompt: req.prompt,
-            response: req.response,
-            model_id: req.model_id,
-            timestamp: req.timestamp || new Date().toISOString(),
-            ...(req.experiment_id ? { experiment_id: req.experiment_id } : {}),
-            ...(req.session_id ? { session_id: req.session_id } : {}),
-            ...(req.parent_evaluation_id ? { parent_evaluation_id: req.parent_evaluation_id } : {}),
-            ...(req.control_pack_id ? { control_pack_id: req.control_pack_id } : {}),
-            ...(req.control_pack_version ? { control_pack_version: req.control_pack_version } : {}),
-            ...(req.dry_run ? { dry_run: req.dry_run } : {}),
-            ...(req.usage ? { usage: req.usage } : {}),
-        });
+            evaluation_id: `local_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            active_control_pack_id: "",
+            active_control_pack_version: 0,
+            data_mode: "unknown",
+            telemetry_mode: "unknown",
+            execution_mode: "sync",
+            decision_action: allowed ? "log_only" : "enforce",
+            decision_source: source,
+            evaluation: {
+                allowed,
+                risk_score: allowed ? 0 : 10,
+                violations: allowed ? [] : [{
+                        clause_id: "DRIFTGARD_UNAVAILABLE",
+                        severity: "critical",
+                        category: "system",
+                        reason: `Driftgard API unavailable — fail-closed policy applied (${source})`,
+                    }],
+            },
+            ...(allowed ? {} : {
+                fallback: {
+                    message: "Service temporarily unavailable. Request blocked by fail-closed policy.",
+                    code: "DRIFTGARD_UNAVAILABLE",
+                    action: "show_message",
+                    source,
+                    escalated: false,
+                    retry_after_ms: this.cbState === "open" ? this.cbResetMs : null,
+                },
+            }),
+        };
+    }
+    /** Get current circuit breaker state (for observability). */
+    get circuitBreakerState() {
+        return { state: this.cbState, failures: this.cbFailures, openedAt: this.cbOpenedAt };
+    }
+    generateIdempotencyKey() {
+        return `idem_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    async post(path, body, attempt = 0) {
+    async post(path, body, idempotencyKey, attempt = 0) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
         try {
@@ -49,6 +133,7 @@ class Driftgard {
                 headers: {
                     "Content-Type": "application/json",
                     "x-api-key": this.apiKey,
+                    ...(idempotencyKey ? { "x-idempotency-key": idempotencyKey } : {}),
                 },
                 body: JSON.stringify(body),
                 signal: controller.signal,
@@ -72,7 +157,7 @@ class Driftgard {
             // Retry on 5xx
             if (res.status >= 500 && attempt < this.maxRetries) {
                 await this.delay(RETRY_DELAY_MS * Math.pow(2, attempt));
-                return this.post(path, body, attempt + 1);
+                return this.post(path, body, idempotencyKey, attempt + 1);
             }
             const payload = await res.json();
             if (!res.ok) {
@@ -86,7 +171,7 @@ class Driftgard {
             // Network error — retry
             if (attempt < this.maxRetries) {
                 await this.delay(RETRY_DELAY_MS * Math.pow(2, attempt));
-                return this.post(path, body, attempt + 1);
+                return this.post(path, body, idempotencyKey, attempt + 1);
             }
             const msg = e instanceof Error ? e.message : String(e);
             throw new errors_1.DriftgardError(msg, 0, "network_error");

package/dist/types.d.ts

@@ -1,8 +1,18 @@
+export interface CircuitBreakerConfig {
+    /** Number of consecutive failures before opening the circuit. Default 5. */
+    threshold?: number;
+    /** Milliseconds to wait before trying again after circuit opens. Default 30000. */
+    resetTimeoutMs?: number;
+}
 export interface DriftgardConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;
+    /** What to do when Driftgard API is unreachable. "open" = allow, "closed" = block. Default "open". */
+    failureMode?: "open" | "closed";
+    /** Circuit breaker config. Skips API calls after consecutive failures. */
+    circuitBreaker?: CircuitBreakerConfig;
 }
 export interface EvaluateRequest {
     project_id: string;
@@ -16,6 +26,8 @@ export interface EvaluateRequest {
     control_pack_id?: string;
     control_pack_version?: number;
     dry_run?: boolean;
+    /** Caller-provided idempotency key. If omitted, the SDK generates one. */
+    idempotency_key?: string;
     usage?: {
         prompt_tokens?: number;
         completion_tokens?: number;
@@ -34,6 +46,8 @@ export interface EvaluationResult {
     allowed: boolean;
     risk_score: number;
     violations: Violation[];
+    /** Original policy decision before execution_mode override (only present when overridden). */
+    policy_allowed?: boolean;
     flags?: {
         pii_detected?: boolean;
         pii_in_prompt?: boolean;
@@ -70,6 +84,12 @@ export interface EvaluateResponse {
     active_control_pack_version: number;
     data_mode: string;
     telemetry_mode: string;
+    /** Server-side execution mode: sync, async, or hybrid. */
+    execution_mode?: string;
+    /** How the decision was applied: "enforce" or "log_only". */
+    decision_action?: string;
+    /** Where the decision came from: "policy", "failure_mode", "circuit_open". */
+    decision_source?: string;
     dry_run?: boolean;
     experiment_id?: string;
     session_id?: string;
@@ -83,4 +103,13 @@ export interface EvaluateResponse {
     hitl?: HitlInfo;
     evaluation: EvaluationResult;
     fallback?: FallbackResponse;
+    cost_alert?: {
+        type: string;
+        scope: string;
+        session_id?: string;
+        model_id?: string;
+        window: string;
+        threshold_usd: number;
+        actual_usd: number;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftgard/node",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Official Driftgard Node.js SDK — evaluate LLM interactions against your compliance policy",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",