agentcheck-sdk 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { DelegationDashboard } from "./dashboard";
 export { quickStart } from "./quickstart";
 export { templates } from "./templates";
 export { TelemetryPlugin } from "./telemetry";
+export { ScopeEngine, buildScope } from "./scope-engine";
+export { SafetyStack, BudgetTracker, PatternMonitor, HumanEscalation } from "./safety";
 export type { WebhookEvent } from "./webhook";
 export type { ScopeVerifier, DelegationProviderConfig } from "./provider";
 export type { GuardConfig } from "./guard";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = exports.TelemetryPlugin = exports.templates = exports.quickStart = exports.DelegationDashboard = exports.AgentToolChecker = exports.delegationGuard = exports.DelegationProvider = exports.WebhookHandler = exports.AgentCheckClient = void 0;
+exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = exports.HumanEscalation = exports.PatternMonitor = exports.BudgetTracker = exports.SafetyStack = exports.buildScope = exports.ScopeEngine = exports.TelemetryPlugin = exports.templates = exports.quickStart = exports.DelegationDashboard = exports.AgentToolChecker = exports.delegationGuard = exports.DelegationProvider = exports.WebhookHandler = exports.AgentCheckClient = void 0;
 // Individual commands (basic menu)
 var client_1 = require("./client");
 Object.defineProperty(exports, "AgentCheckClient", { enumerable: true, get: function () { return client_1.AgentCheckClient; } });
@@ -21,6 +21,14 @@ var templates_1 = require("./templates");
 Object.defineProperty(exports, "templates", { enumerable: true, get: function () { return templates_1.templates; } });
 var telemetry_1 = require("./telemetry");
 Object.defineProperty(exports, "TelemetryPlugin", { enumerable: true, get: function () { return telemetry_1.TelemetryPlugin; } });
+var scope_engine_1 = require("./scope-engine");
+Object.defineProperty(exports, "ScopeEngine", { enumerable: true, get: function () { return scope_engine_1.ScopeEngine; } });
+Object.defineProperty(exports, "buildScope", { enumerable: true, get: function () { return scope_engine_1.buildScope; } });
+var safety_1 = require("./safety");
+Object.defineProperty(exports, "SafetyStack", { enumerable: true, get: function () { return safety_1.SafetyStack; } });
+Object.defineProperty(exports, "BudgetTracker", { enumerable: true, get: function () { return safety_1.BudgetTracker; } });
+Object.defineProperty(exports, "PatternMonitor", { enumerable: true, get: function () { return safety_1.PatternMonitor; } });
+Object.defineProperty(exports, "HumanEscalation", { enumerable: true, get: function () { return safety_1.HumanEscalation; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "AgentCheckError", { enumerable: true, get: function () { return errors_1.AgentCheckError; } });
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });

package/dist/safety.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Safety Layers - Multi-layered action verification.
+ *
+ * Layer 1: ScopeEngine      - "What is it doing?"
+ * Layer 2: BudgetTracker    - "How much total?"
+ * Layer 3: PatternMonitor   - "Is this normal?"
+ * Layer 4: HumanEscalation  - "Should a human decide?"
+ */
+import { ScopeEngine, StructuredScope, VerificationResult } from "./scope-engine";
+export declare class BudgetTracker {
+    private dailyLimit?;
+    private monthlyLimit?;
+    private dailyCountLimit?;
+    private dailyTotals;
+    private dailyCounts;
+    private monthlyTotals;
+    constructor(opts: {
+        dailyLimit?: number;
+        monthlyLimit?: number;
+        dailyCountLimit?: number;
+    });
+    check(action: string, amount?: number): VerificationResult;
+    recordUsage(action: string, amount?: number): void;
+}
+export interface PatternAlert {
+    level: "warning" | "critical";
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare class PatternMonitor {
+    private history;
+    private windowDays;
+    private threshold;
+    constructor(windowDays?: number, frequencyThreshold?: number);
+    record(action: string, amount?: number): void;
+    check(action: string, amount?: number): PatternAlert[];
+}
+export declare class HumanEscalation {
+    private threshold?;
+    private highRiskActions;
+    private onEscalate?;
+    constructor(opts: {
+        thresholdAmount?: number;
+        highRiskActions?: string[];
+        onEscalate?: (action: string, amount: number) => void;
+    });
+    check(action: string, amount?: number): VerificationResult;
+}
+export interface SafetyResult {
+    allowed: boolean;
+    passedLayers: string[];
+    failedLayer?: string;
+    reason: string;
+    alerts: PatternAlert[];
+}
+export declare class SafetyStack {
+    private scopeEngine;
+    private budget?;
+    private pattern?;
+    private escalation?;
+    constructor(opts?: {
+        scopeEngine?: ScopeEngine;
+        budget?: BudgetTracker;
+        pattern?: PatternMonitor;
+        escalation?: HumanEscalation;
+    });
+    check(scope: StructuredScope | string, action: string, amount?: number): SafetyResult;
+    recordExecution(action: string, amount?: number): void;
+}

package/dist/safety.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Safety Layers - Multi-layered action verification.
+ *
+ * Layer 1: ScopeEngine      - "What is it doing?"
+ * Layer 2: BudgetTracker    - "How much total?"
+ * Layer 3: PatternMonitor   - "Is this normal?"
+ * Layer 4: HumanEscalation  - "Should a human decide?"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafetyStack = exports.HumanEscalation = exports.PatternMonitor = exports.BudgetTracker = void 0;
+const scope_engine_1 = require("./scope-engine");
+// ── Layer 2: Budget Tracker ──
+class BudgetTracker {
+    constructor(opts) {
+        this.dailyTotals = {};
+        this.dailyCounts = {};
+        this.monthlyTotals = {};
+        this.dailyLimit = opts.dailyLimit;
+        this.monthlyLimit = opts.monthlyLimit;
+        this.dailyCountLimit = opts.dailyCountLimit;
+    }
+    check(action, amount = 0) {
+        const dayKey = new Date().toISOString().slice(0, 10);
+        const monthKey = dayKey.slice(0, 7);
+        if (this.dailyCountLimit && (this.dailyCounts[dayKey] || 0) >= this.dailyCountLimit) {
+            return { allowed: false, reason: `Daily action count limit reached (${this.dailyCountLimit})` };
+        }
+        if (this.dailyLimit && amount > 0) {
+            const projected = (this.dailyTotals[dayKey] || 0) + amount;
+            if (projected > this.dailyLimit) {
+                return { allowed: false, reason: `Daily budget exceeded: ${projected} > ${this.dailyLimit}` };
+            }
+        }
+        if (this.monthlyLimit && amount > 0) {
+            const projected = (this.monthlyTotals[monthKey] || 0) + amount;
+            if (projected > this.monthlyLimit) {
+                return { allowed: false, reason: `Monthly budget exceeded: ${projected} > ${this.monthlyLimit}` };
+            }
+        }
+        return { allowed: true, reason: "Within budget" };
+    }
+    recordUsage(action, amount = 0) {
+        const dayKey = new Date().toISOString().slice(0, 10);
+        const monthKey = dayKey.slice(0, 7);
+        this.dailyTotals[dayKey] = (this.dailyTotals[dayKey] || 0) + amount;
+        this.dailyCounts[dayKey] = (this.dailyCounts[dayKey] || 0) + 1;
+        this.monthlyTotals[monthKey] = (this.monthlyTotals[monthKey] || 0) + amount;
+    }
+}
+exports.BudgetTracker = BudgetTracker;
+class PatternMonitor {
+    constructor(windowDays = 7, frequencyThreshold = 3.0) {
+        this.history = [];
+        this.windowDays = windowDays;
+        this.threshold = frequencyThreshold;
+    }
+    record(action, amount = 0) {
+        this.history.push({ action, amount, timestamp: Date.now() });
+    }
+    check(action, amount = 0) {
+        const alerts = [];
+        const cutoff = Date.now() - this.windowDays * 86400000;
+        const recent = this.history.filter(h => h.action === action && h.timestamp > cutoff);
+        if (recent.length < 3)
+            return alerts;
+        const todayStart = new Date();
+        todayStart.setHours(0, 0, 0, 0);
+        const todayCount = recent.filter(h => h.timestamp >= todayStart.getTime()).length;
+        const uniqueDays = new Set(recent.map(h => new Date(h.timestamp).toDateString())).size;
+        const avgDaily = recent.length / Math.max(uniqueDays, 1);
+        if (avgDaily > 0 && todayCount > avgDaily * this.threshold) {
+            alerts.push({
+                level: "warning",
+                message: `Unusual frequency: ${todayCount} today vs ${avgDaily.toFixed(1)} avg/day (${(todayCount / avgDaily).toFixed(1)}x normal)`,
+            });
+        }
+        if (amount > 0) {
+            const amounts = recent.filter(h => h.amount > 0).map(h => h.amount);
+            if (amounts.length) {
+                const avg = amounts.reduce((a, b) => a + b, 0) / amounts.length;
+                if (amount > avg * this.threshold) {
+                    alerts.push({
+                        level: "warning",
+                        message: `Unusual amount: ${amount} vs ${avg.toFixed(0)} avg (${(amount / avg).toFixed(1)}x normal)`,
+                    });
+                }
+            }
+        }
+        return alerts;
+    }
+}
+exports.PatternMonitor = PatternMonitor;
+// ── Layer 4: Human Escalation ──
+class HumanEscalation {
+    constructor(opts) {
+        this.threshold = opts.thresholdAmount;
+        this.highRiskActions = opts.highRiskActions || [];
+        this.onEscalate = opts.onEscalate;
+    }
+    check(action, amount = 0) {
+        let needsApproval = false;
+        let reason = "";
+        if (this.highRiskActions.includes(action)) {
+            needsApproval = true;
+            reason = `Action '${action}' is classified as high-risk`;
+        }
+        if (this.threshold && amount > this.threshold) {
+            needsApproval = true;
+            reason = `Amount ${amount} exceeds escalation threshold ${this.threshold}`;
+        }
+        if (needsApproval) {
+            this.onEscalate?.(action, amount);
+            return { allowed: false, reason: `Requires human approval: ${reason}`, details: { needs_human_approval: true } };
+        }
+        return { allowed: true, reason: "No escalation needed" };
+    }
+}
+exports.HumanEscalation = HumanEscalation;
+class SafetyStack {
+    constructor(opts = {}) {
+        this.scopeEngine = opts.scopeEngine || new scope_engine_1.ScopeEngine();
+        this.budget = opts.budget;
+        this.pattern = opts.pattern;
+        this.escalation = opts.escalation;
+    }
+    check(scope, action, amount = 0) {
+        const passed = [];
+        const alerts = [];
+        const r1 = this.scopeEngine.verify(scope, action, { amount });
+        if (!r1.allowed)
+            return { allowed: false, passedLayers: passed, failedLayer: "scope_engine", reason: r1.reason, alerts };
+        passed.push("scope_engine");
+        if (this.budget) {
+            const r2 = this.budget.check(action, amount);
+            if (!r2.allowed)
+                return { allowed: false, passedLayers: passed, failedLayer: "budget_tracker", reason: r2.reason, alerts };
+            passed.push("budget_tracker");
+        }
+        if (this.pattern) {
+            const pa = this.pattern.check(action, amount);
+            alerts.push(...pa);
+            const critical = pa.filter(a => a.level === "critical");
+            if (critical.length)
+                return { allowed: false, passedLayers: passed, failedLayer: "pattern_monitor", reason: critical[0].message, alerts };
+            passed.push("pattern_monitor");
+        }
+        if (this.escalation) {
+            const r4 = this.escalation.check(action, amount);
+            if (!r4.allowed)
+                return { allowed: false, passedLayers: passed, failedLayer: "human_escalation", reason: r4.reason, alerts };
+            passed.push("human_escalation");
+        }
+        return { allowed: true, passedLayers: passed, reason: "All safety layers passed", alerts };
+    }
+    recordExecution(action, amount = 0) {
+        this.budget?.recordUsage(action, amount);
+        this.pattern?.record(action, amount);
+    }
+}
+exports.SafetyStack = SafetyStack;

package/dist/scope-engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Scope Engine - Structured scope verification.
+ *
+ * Automatic action verification when scope is structured JSON.
+ * Free-text scope: customers verify themselves.
+ * Structured scope: this engine verifies automatically.
+ */
+export interface StructuredScope {
+    allowed?: string[];
+    denied?: string[];
+    limits?: Record<string, {
+        max_amount?: number;
+        currency?: string;
+        max_count_per_day?: number;
+    }>;
+    schedule?: {
+        timezone?: string;
+        allowed_hours?: [number, number];
+        allowed_days?: number[];
+    };
+    require_approval_above?: {
+        amount: number;
+    };
+}
+export interface VerificationResult {
+    allowed: boolean;
+    reason: string;
+    details?: Record<string, unknown>;
+}
+export declare class ScopeEngine {
+    /** Parse scope string. Returns structured object or raw string. */
+    parse(scopeStr: string): StructuredScope | string;
+    /** Verify if an action is allowed by the scope. */
+    verify(scope: StructuredScope | string, action: string, opts?: {
+        amount?: number;
+        timestamp?: Date;
+    }): VerificationResult;
+}
+/** Build a structured scope JSON string. */
+export declare function buildScope(opts: StructuredScope): string;

package/dist/scope-engine.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Scope Engine - Structured scope verification.
+ *
+ * Automatic action verification when scope is structured JSON.
+ * Free-text scope: customers verify themselves.
+ * Structured scope: this engine verifies automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeEngine = void 0;
+exports.buildScope = buildScope;
+class ScopeEngine {
+    /** Parse scope string. Returns structured object or raw string. */
+    parse(scopeStr) {
+        try {
+            const parsed = JSON.parse(scopeStr);
+            if (typeof parsed === "object" && ("allowed" in parsed || "denied" in parsed)) {
+                return parsed;
+            }
+        }
+        catch { }
+        return scopeStr;
+    }
+    /** Verify if an action is allowed by the scope. */
+    verify(scope, action, opts = {}) {
+        if (typeof scope === "string") {
+            return {
+                allowed: true,
+                reason: "Free-text scope: automatic verification not available. Verify manually.",
+                details: { scope_type: "free-text" },
+            };
+        }
+        // Denied list (highest priority)
+        if (scope.denied?.includes(action)) {
+            return { allowed: false, reason: `Action '${action}' is in denied list` };
+        }
+        // Allowed list
+        if (scope.allowed?.length && !scope.allowed.includes(action)) {
+            return { allowed: false, reason: `Action '${action}' not in allowed list: ${scope.allowed.join(", ")}` };
+        }
+        // Amount limits
+        if (opts.amount !== undefined && scope.limits?.[action]) {
+            const limit = scope.limits[action];
+            if (limit.max_amount !== undefined && opts.amount > limit.max_amount) {
+                return {
+                    allowed: false,
+                    reason: `Amount ${opts.amount} exceeds limit ${limit.max_amount} ${limit.currency || ""}`,
+                    details: { limit: limit.max_amount, actual: opts.amount },
+                };
+            }
+        }
+        // Escalation threshold
+        if (opts.amount !== undefined && scope.require_approval_above) {
+            if (opts.amount > scope.require_approval_above.amount) {
+                return {
+                    allowed: false,
+                    reason: `Amount ${opts.amount} requires additional approval (threshold: ${scope.require_approval_above.amount})`,
+                    details: { threshold: scope.require_approval_above.amount, actual: opts.amount },
+                };
+            }
+        }
+        // Schedule check
+        if (opts.timestamp && scope.schedule) {
+            const hours = scope.schedule.allowed_hours;
+            if (hours && (opts.timestamp.getHours() < hours[0] || opts.timestamp.getHours() >= hours[1])) {
+                return { allowed: false, reason: `Action not allowed at hour ${opts.timestamp.getHours()} (allowed: ${hours[0]}-${hours[1]})` };
+            }
+            const days = scope.schedule.allowed_days;
+            const day = opts.timestamp.getDay() || 7; // Sunday=7
+            if (days && !days.includes(day)) {
+                return { allowed: false, reason: `Action not allowed on day ${day}` };
+            }
+        }
+        return { allowed: true, reason: "Action verified: within scope" };
+    }
+}
+exports.ScopeEngine = ScopeEngine;
+/** Build a structured scope JSON string. */
+function buildScope(opts) {
+    return JSON.stringify(opts);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcheck-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Record what your AI agent is allowed to do",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",