@driftgard/node 1.4.0 → 1.5.1

package/README.md

@@ -27,10 +27,31 @@ const result = await dg.evaluate({
 if (result.evaluation.allowed) {
   console.log("Safe to return to user");
 } else {
+  // Use the fallback message if configured in your control pack
+  if (result.fallback) {
+    console.log("Show to user:", result.fallback.message);
+  }
   console.log("Blocked:", result.evaluation.violations);
 }
 ```
 
+## Conversation tracking
+
+Link evaluations within an agent session using `session_id` and `parent_evaluation_id`:
+
+```typescript
+const result = await dg.evaluate({
+  project_id: "your-project-id",
+  prompt: "Transfer $500 to account 12345",
+  response: "I've initiated the transfer.",
+  model_id: "gpt-4o",
+  session_id: "sess_abc123",              // groups evals in a conversation
+  parent_evaluation_id: "eval_prev_id",   // chains to the previous eval
+});
+```
+
+This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard.
+
 ## A/B experiments
 
 Tag evaluations with an `experiment_id` to compare governance metrics across models:
@@ -67,13 +88,15 @@ 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.
-```
 
 ## 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`
+- Typed errors: `AuthError`, `RateLimitError`, `FeatureNotAvailableError`, `ChainDepthExceededError`
 - Full TypeScript types for requests and responses
 - Zero dependencies (uses native `fetch`)
 
@@ -85,13 +108,39 @@ 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
-import { Driftgard, AuthError, RateLimitError, FeatureNotAvailableError } from "@driftgard/node";
+import { Driftgard, AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError } from "@driftgard/node";
 
 try {
   const result = await dg.evaluate({ ... });
@@ -100,6 +149,9 @@ try {
     // Invalid or revoked API key (401)
   } else if (e instanceof RateLimitError) {
     // Too many requests (429)
+  } else if (e instanceof ChainDepthExceededError) {
+    // Agent loop detected — chain depth exceeded (429)
+    console.log(`Depth ${e.depth} exceeds max ${e.max}`);
   } else if (e instanceof FeatureNotAvailableError) {
     // API evaluate requires Compliance+ tier (403)
   }

package/dist/errors.d.ts

@@ -13,3 +13,8 @@ export declare class FeatureNotAvailableError extends DriftgardError {
     tier: string;
     constructor(message?: string, tier?: string);
 }
+export declare class ChainDepthExceededError extends DriftgardError {
+    depth: number;
+    max: number;
+    constructor(message?: string, depth?: number, max?: number);
+}

package/dist/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FeatureNotAvailableError = exports.RateLimitError = exports.AuthError = exports.DriftgardError = void 0;
+exports.ChainDepthExceededError = exports.FeatureNotAvailableError = exports.RateLimitError = exports.AuthError = exports.DriftgardError = void 0;
 class DriftgardError extends Error {
     constructor(message, status, code) {
         super(message);
@@ -32,3 +32,12 @@ class FeatureNotAvailableError extends DriftgardError {
     }
 }
 exports.FeatureNotAvailableError = FeatureNotAvailableError;
+class ChainDepthExceededError extends DriftgardError {
+    constructor(message = "Evaluation chain depth exceeded", depth = 0, max = 0) {
+        super(message, 429, "chain_depth_exceeded");
+        this.name = "ChainDepthExceededError";
+        this.depth = depth;
+        this.max = max;
+    }
+}
+exports.ChainDepthExceededError = ChainDepthExceededError;

package/dist/index.d.ts

@@ -1,17 +1,34 @@
 import { DriftgardConfig, EvaluateRequest, EvaluateResponse } from "./types";
-export { DriftgardConfig, EvaluateRequest, EvaluateResponse } from "./types";
-export { Violation, EvaluationResult, HitlInfo } from "./types";
-export { DriftgardError, AuthError, RateLimitError, FeatureNotAvailableError } from "./errors";
+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

@@ -1,40 +1,130 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Driftgard = exports.FeatureNotAvailableError = exports.RateLimitError = exports.AuthError = exports.DriftgardError = void 0;
+exports.Driftgard = exports.ChainDepthExceededError = exports.FeatureNotAvailableError = exports.RateLimitError = exports.AuthError = exports.DriftgardError = void 0;
 const errors_1 = require("./errors");
 var errors_2 = require("./errors");
 Object.defineProperty(exports, "DriftgardError", { enumerable: true, get: function () { return errors_2.DriftgardError; } });
 Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_2.AuthError; } });
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_2.RateLimitError; } });
 Object.defineProperty(exports, "FeatureNotAvailableError", { enumerable: true, get: function () { return errors_2.FeatureNotAvailableError; } });
+Object.defineProperty(exports, "ChainDepthExceededError", { enumerable: true, get: function () { return errors_2.ChainDepthExceededError; } });
 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.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 };
     }
-    async post(path, body, attempt = 0) {
+    generateIdempotencyKey() {
+        return `idem_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    async post(path, body, idempotencyKey, attempt = 0) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
         try {
@@ -43,14 +133,20 @@ class Driftgard {
                 headers: {
                     "Content-Type": "application/json",
                     "x-api-key": this.apiKey,
+                    ...(idempotencyKey ? { "x-idempotency-key": idempotencyKey } : {}),
                 },
                 body: JSON.stringify(body),
                 signal: controller.signal,
             });
             if (res.status === 401)
                 throw new errors_1.AuthError();
-            if (res.status === 429)
+            if (res.status === 429) {
+                const payload = await res.json().catch(() => ({}));
+                if (payload?.error === "chain_depth_exceeded") {
+                    throw new errors_1.ChainDepthExceededError(payload.message, payload.depth, payload.max);
+                }
                 throw new errors_1.RateLimitError();
+            }
             if (res.status === 403) {
                 const payload = await res.json().catch(() => ({}));
                 if (payload?.error === "feature_not_available") {
@@ -61,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) {
@@ -75,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;
@@ -11,6 +21,13 @@ export interface EvaluateRequest {
     model_id: string;
     timestamp?: string;
     experiment_id?: string;
+    session_id?: string;
+    parent_evaluation_id?: string;
+    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;
@@ -29,9 +46,15 @@ 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;
+        secret_detected?: boolean;
+        adversarial_input?: boolean;
+        adversarial_score?: number;
+        dlp_findings_count?: number;
         meta_bypass_detected?: boolean;
         judge_used?: boolean;
         judge_called?: boolean;
@@ -39,6 +62,14 @@ export interface EvaluationResult {
         hard_blocked?: boolean;
     };
 }
+export interface FallbackResponse {
+    message: string;
+    code: string;
+    action: string;
+    source: string;
+    escalated: boolean;
+    retry_after_ms?: number | null;
+}
 export interface HitlInfo {
     queued: boolean;
     hitl_id?: string;
@@ -53,6 +84,23 @@ export interface EvaluateResponse {
     active_control_pack_version: number;
     data_mode: string;
     telemetry_mode: string;
-    hitl: HitlInfo;
+    /** 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;
+    parent_evaluation_id?: string;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        cost?: number;
+    };
+    hitl?: HitlInfo;
     evaluation: EvaluationResult;
+    fallback?: FallbackResponse;
 }

package/package.json

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