agentcheck-sdk 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { DelegationDashboard } from "./dashboard";
 export { quickStart } from "./quickstart";
 export { templates } from "./templates";
 export { TelemetryPlugin } from "./telemetry";
+export { ScopeEngine, buildScope } from "./scope-engine";
 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.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,9 @@ 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 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/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.7.0",
   "description": "Record what your AI agent is allowed to do",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",