@driftgard/node 1.6.0 → 1.8.0

package/README.md

@@ -47,10 +47,11 @@ const result = await dg.evaluate({
   model_id: "gpt-4o",
   session_id: "sess_abc123",              // groups evals in a conversation
   parent_evaluation_id: "eval_prev_id",   // chains to the previous eval
+  sequence_no: 1,                          // optional — enforces ordering within session
 });
 ```
 
-This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard.
+This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard. When `sequence_no` is provided, Driftgard enforces ordering — if an eval arrives out of order, the response includes a `sequence_warning`.
 
 ## A/B experiments
 
@@ -104,6 +105,37 @@ if (result.cost_alert) {
 
 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,9 @@ 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.sequence_no != null ? { sequence_no: req.sequence_no } : {}),
                 ...(req.usage ? { usage: req.usage } : {}),
             }, idempotencyKey);
             // Success — reset circuit breaker
@@ -117,6 +120,53 @@ 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,
+            sequence_no: req.sequence_no,
+        });
+    }
+    /**
+     * 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,8 +26,15 @@ 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;
+    /** Sequence number within a session for ordering. Optional — if sent, ordering is enforced. */
+    sequence_no?: number;
     usage?: {
         prompt_tokens?: number;
         completion_tokens?: number;
@@ -112,4 +119,35 @@ export interface EvaluateResponse {
         threshold_usd: number;
         actual_usd: number;
     };
+    eval_mode?: string;
+    tool_call?: {
+        tool_name: string;
+        parameters?: Record<string, any>;
+    };
+    sequence_no?: number;
+    sequence_warning?: {
+        message: string;
+        expected_next: number;
+        received: number;
+        max_seen: number;
+    };
+}
+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;
+    sequence_no?: number;
+}
+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.6.0",
+  "version": "1.8.0",
   "description": "Official Driftgard Node.js SDK — evaluate LLM interactions against your compliance policy",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",