@driftgard/node 1.5.1 → 1.7.0

package/README.md

@@ -89,6 +89,52 @@ 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.
+
+## Tool call validation
+
+Validate AI agent tool/function calls against your control pack's tool rules:
+
+```typescript
+// Direct tool call evaluation
+const result = await dg.evaluateToolCall({
+  project_id: "your-project-id",
+  model_id: "gpt-4o",
+  tool_name: "transfer_money",
+  parameters: { amount: 500, to_account: "account_123" },
+  session_id: "sess_abc123",
+});
+
+if (!result.evaluation.allowed) {
+  console.log("Tool blocked:", result.fallback?.message);
+}
+
+// Or wrap a tool function — blocks automatically
+const safeTransfer = dg.guard(transferMoney, "transfer_money", "your-project-id");
+await safeTransfer({ amount: 500, to_account: "account_123" }); // throws if blocked
+
+// Report execution outcome (optional)
+await dg.reportOutcome(result.evaluation_id, "your-project-id", {
+  execution_status: "success",
+  duration_ms: 230,
+});
+```
+
+For Strands agents, use the `BeforeToolCallEvent` hook — see the integration guide.
+
 ## Features
 
 - Single `evaluate()` method — send prompt/response, get verdict

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { DriftgardConfig, EvaluateRequest, EvaluateResponse } from "./types";
-export { DriftgardConfig, EvaluateRequest, EvaluateResponse, CircuitBreakerConfig } from "./types";
+import { DriftgardConfig, EvaluateRequest, EvaluateResponse, ToolCallRequest, OutcomeRequest } from "./types";
+export { DriftgardConfig, EvaluateRequest, EvaluateResponse, CircuitBreakerConfig, ToolCallRequest, OutcomeRequest } from "./types";
 export { Violation, EvaluationResult, FallbackResponse, HitlInfo } from "./types";
 export { DriftgardError, AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError } from "./errors";
 type CircuitState = "closed" | "open" | "half-open";
@@ -22,6 +22,22 @@ export declare class Driftgard {
     evaluate(req: EvaluateRequest): Promise<EvaluateResponse>;
     /** Generate a synthetic response based on failure mode. */
     private syntheticResponse;
+    /**
+     * Evaluate a tool/function call against your control pack's tool_rules.
+     */
+    evaluateToolCall(req: ToolCallRequest): Promise<EvaluateResponse>;
+    /**
+     * Report the outcome of a tool execution after it was allowed.
+     */
+    reportOutcome(evaluationId: string, projectId: string, outcome: OutcomeRequest): Promise<any>;
+    /**
+     * Wrap a tool function with Driftgard policy check.
+     * Returns a guarded version that evaluates before executing.
+     */
+    guard<T extends (...args: any[]) => any>(toolFn: T, toolName: string, projectId: string, opts?: {
+        modelId?: string;
+        sessionId?: string;
+    }): (...args: Parameters<T>) => Promise<ReturnType<T>>;
     /** Get current circuit breaker state (for observability). */
     get circuitBreakerState(): {
         state: CircuitState;

package/dist/index.js

@@ -58,6 +58,8 @@ class Driftgard {
                 ...(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.eval_mode ? { eval_mode: req.eval_mode } : {}),
+                ...(req.tool_call ? { tool_call: req.tool_call } : {}),
                 ...(req.usage ? { usage: req.usage } : {}),
             }, idempotencyKey);
             // Success — reset circuit breaker
@@ -117,6 +119,52 @@ class Driftgard {
             }),
         };
     }
+    /**
+     * Evaluate a tool/function call against your control pack's tool_rules.
+     */
+    async evaluateToolCall(req) {
+        return this.evaluate({
+            project_id: req.project_id,
+            prompt: "",
+            response: "",
+            model_id: req.model_id,
+            eval_mode: "tool_call",
+            tool_call: { tool_name: req.tool_name, parameters: req.parameters || {} },
+            session_id: req.session_id,
+            parent_evaluation_id: req.parent_evaluation_id,
+            idempotency_key: req.idempotency_key,
+        });
+    }
+    /**
+     * Report the outcome of a tool execution after it was allowed.
+     */
+    async reportOutcome(evaluationId, projectId, outcome) {
+        return this.post(`/audit/evaluations/${encodeURIComponent(evaluationId)}/outcome`, {
+            project_id: projectId,
+            ...outcome,
+        });
+    }
+    /**
+     * Wrap a tool function with Driftgard policy check.
+     * Returns a guarded version that evaluates before executing.
+     */
+    guard(toolFn, toolName, projectId, opts) {
+        const dg = this;
+        return async (...args) => {
+            const parameters = args.length === 1 && typeof args[0] === "object" ? args[0] : { args };
+            const result = await dg.evaluateToolCall({
+                project_id: projectId,
+                model_id: opts?.modelId || "agent",
+                tool_name: toolName,
+                parameters,
+                session_id: opts?.sessionId,
+            });
+            if (!result.evaluation.allowed) {
+                throw new errors_1.DriftgardError(result.fallback?.message || `Tool "${toolName}" blocked by policy`, 403, "tool_blocked");
+            }
+            return toolFn(...args);
+        };
+    }
     /** Get current circuit breaker state (for observability). */
     get circuitBreakerState() {
         return { state: this.cbState, failures: this.cbFailures, openedAt: this.cbOpenedAt };

package/dist/types.d.ts

@@ -26,6 +26,11 @@ export interface EvaluateRequest {
     control_pack_id?: string;
     control_pack_version?: number;
     dry_run?: boolean;
+    eval_mode?: "text" | "tool_call";
+    tool_call?: {
+        tool_name: string;
+        parameters?: Record<string, any>;
+    };
     /** Caller-provided idempotency key. If omitted, the SDK generates one. */
     idempotency_key?: string;
     usage?: {
@@ -103,4 +108,36 @@ 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;
+    };
+    eval_mode?: string;
+    tool_call?: {
+        tool_name: string;
+        parameters?: Record<string, any>;
+    };
+}
+export interface ToolCallRequest {
+    project_id: string;
+    model_id: string;
+    tool_name: string;
+    parameters?: Record<string, any>;
+    session_id?: string;
+    parent_evaluation_id?: string;
+    idempotency_key?: string;
+}
+export interface OutcomeRequest {
+    execution_status: "success" | "failed" | "rolled_back";
+    duration_ms?: number;
+    error_code?: string;
+    error_message?: string;
+    affected_resources?: string[];
+    compensation_action?: string;
+    external_ref?: string;
 }

package/package.json

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