npm - agentcheck-sdk - Versions diffs - 0.1.0 → 0.3.0 - Mend

agentcheck-sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/dist/client.d.ts CHANGED Viewed

@@ -3,7 +3,7 @@ export declare class AgentCheckClient {
     private apiKey;
     private baseUrl;
     constructor(apiKey: string, baseUrl?: string);
-    private request;
+    request<T>(method: string, path: string, body?: unknown, auth?: boolean): Promise<T>;
     /** Create a new agreement and send approval email. */
     record(params: CreateRecordParams): Promise<Agreement>;
     /** Get agreement details by ID. */

package/dist/dashboard.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+import { AgentCheckClient } from "./client";
+export interface DashboardConfig {
+    /** Title shown at the top */
+    title?: string;
+    /** Auto-refresh interval in seconds (0 = off) */
+    refreshInterval?: number;
+    /** Max records to show */
+    limit?: number;
+}
+/**
+ * DelegationDashboard - Embeddable HTML widget for agent delegation status.
+ *
+ * Generates a self-contained HTML snippet that shows:
+ * - Active delegations with status badges
+ * - Recent execution logs
+ * - Quick actions (revoke)
+ *
+ * Usage (Express):
+ *   app.get('/admin/delegations', async (req, res) => {
+ *     const html = await dashboard.render();
+ *     res.send(html);
+ *   });
+ *
+ * Usage (embed in existing page):
+ *   const html = await dashboard.renderWidget();
+ *   // Insert into your page's <div id="delegation-widget">
+ */
+export declare class DelegationDashboard {
+    private client;
+    private config;
+    constructor(client: AgentCheckClient, config?: DashboardConfig);
+    /** Render full HTML page with dashboard. */
+    render(): Promise<string>;
+    /** Render widget HTML (for embedding in existing pages). */
+    renderWidget(): Promise<string>;
+}

package/dist/dashboard.js ADDED Viewed

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationDashboard = void 0;
+/**
+ * DelegationDashboard - Embeddable HTML widget for agent delegation status.
+ *
+ * Generates a self-contained HTML snippet that shows:
+ * - Active delegations with status badges
+ * - Recent execution logs
+ * - Quick actions (revoke)
+ *
+ * Usage (Express):
+ *   app.get('/admin/delegations', async (req, res) => {
+ *     const html = await dashboard.render();
+ *     res.send(html);
+ *   });
+ *
+ * Usage (embed in existing page):
+ *   const html = await dashboard.renderWidget();
+ *   // Insert into your page's <div id="delegation-widget">
+ */
+class DelegationDashboard {
+    constructor(client, config = {}) {
+        this.client = client;
+        this.config = {
+            title: config.title ?? "Agent Delegations",
+            refreshInterval: config.refreshInterval ?? 30,
+            limit: config.limit ?? 20,
+        };
+    }
+    /** Render full HTML page with dashboard. */
+    async render() {
+        const widget = await this.renderWidget();
+        const refresh = this.config.refreshInterval > 0
+            ? `<meta http-equiv="refresh" content="${this.config.refreshInterval}">`
+            : "";
+        return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+${refresh}
+<title>${this.config.title}</title>
+<style>${DASHBOARD_CSS}</style>
+</head><body>${widget}</body></html>`;
+    }
+    /** Render widget HTML (for embedding in existing pages). */
+    async renderWidget() {
+        const list = await this.client.list({ limit: this.config.limit });
+        const records = list.records;
+        const statusCounts = {};
+        for (const r of records) {
+            statusCounts[r.status] = (statusCounts[r.status] || 0) + 1;
+        }
+        const summaryCards = Object.entries(statusCounts)
+            .map(([status, count]) => `<div class="ac-card"><div class="ac-card-num">${count}</div><div class="ac-card-label">${status}</div></div>`).join("\n");
+        const rows = records
+            .map((r) => {
+            const statusClass = r.status === "approved" ? "ac-approved"
+                : r.status === "revoked" ? "ac-revoked"
+                    : r.status === "expired" ? "ac-expired"
+                        : "ac-pending";
+            return `<tr>
+          <td><span class="ac-badge ${statusClass}">${r.status}</span></td>
+          <td>${r.agent}</td>
+          <td title="${r.scope}">${r.scope.length > 60 ? r.scope.slice(0, 60) + "..." : r.scope}</td>
+          <td>${r.authorized_by}</td>
+          <td>${new Date(r.created_at).toLocaleDateString()}</td>
+          <td><a href="${r.verify_url}" target="_blank">Verify</a></td>
+        </tr>`;
+        }).join("\n");
+        return `<div class="ac-dashboard">
+  <h2 class="ac-title">${this.config.title}</h2>
+  <div class="ac-cards">${summaryCards}</div>
+  <table class="ac-table">
+    <thead><tr>
+      <th>Status</th><th>Agent</th><th>Scope</th><th>Authorized by</th><th>Created</th><th>Verify</th>
+    </tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+  <div class="ac-footer">${records.length} delegation(s) | ${this.config.refreshInterval > 0 ? `Auto-refresh: ${this.config.refreshInterval}s` : "Manual refresh"}</div>
+</div>
+<style>${DASHBOARD_CSS}</style>`;
+    }
+}
+exports.DelegationDashboard = DelegationDashboard;
+const DASHBOARD_CSS = `
+.ac-dashboard{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;max-width:960px;margin:0 auto;padding:24px;}
+.ac-title{font-size:20px;font-weight:700;margin:0 0 20px;color:#1e293b;}
+.ac-cards{display:flex;gap:12px;margin-bottom:20px;flex-wrap:wrap;}
+.ac-card{background:#fff;border:1px solid #e5e7eb;border-radius:10px;padding:16px 20px;min-width:100px;text-align:center;}
+.ac-card-num{font-size:28px;font-weight:800;color:#1e293b;}
+.ac-card-label{font-size:12px;color:#64748b;text-transform:uppercase;letter-spacing:.5px;margin-top:4px;}
+.ac-table{width:100%;border-collapse:collapse;background:#fff;border-radius:10px;overflow:hidden;border:1px solid #e5e7eb;}
+.ac-table th{padding:10px 14px;text-align:left;font-size:12px;font-weight:700;color:#475569;background:#f8fafc;border-bottom:2px solid #e5e7eb;}
+.ac-table td{padding:10px 14px;font-size:13px;color:#555;border-bottom:1px solid #f0f0f0;}
+.ac-table a{color:#2563eb;font-size:12px;}
+.ac-badge{display:inline-block;padding:2px 10px;border-radius:9999px;font-size:11px;font-weight:700;color:#fff;}
+.ac-approved{background:#16a34a;}
+.ac-pending{background:#ca8a04;}
+.ac-revoked{background:#dc2626;}
+.ac-expired{background:#6b7280;}
+.ac-footer{text-align:center;color:#94a3b8;font-size:12px;margin-top:16px;}
+`;

package/dist/guard.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import { DelegationProvider } from "./provider";
+type RequestLike = {
+    headers: Record<string, string | string[] | undefined>;
+    body?: any;
+    path?: string;
+    method?: string;
+};
+type ResponseLike = {
+    status: (code: number) => ResponseLike;
+    json: (body: any) => void;
+};
+type NextFn = () => void | Promise<void>;
+export interface GuardConfig {
+    /** Extract agent name from request (e.g. from header, body, or JWT) */
+    getAgent: (req: RequestLike) => string | undefined;
+    /** Extract action name from request (e.g. from path or body) */
+    getAction: (req: RequestLike) => string;
+}
+/**
+ * DelegationGuard - Express/Fastify middleware.
+ *
+ * Automatically checks delegation before each request.
+ *
+ * Usage:
+ *   app.use('/api/agent/*', delegationGuard(provider, {
+ *     getAgent: (req) => req.headers['x-agent-id'],
+ *     getAction: (req) => `${req.method} ${req.path}`,
+ *   }));
+ */
+export declare function delegationGuard(provider: DelegationProvider, config: GuardConfig): (req: RequestLike, res: ResponseLike, next: NextFn) => Promise<void>;
+export {};

package/dist/guard.js ADDED Viewed

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegationGuard = delegationGuard;
+/**
+ * DelegationGuard - Express/Fastify middleware.
+ *
+ * Automatically checks delegation before each request.
+ *
+ * Usage:
+ *   app.use('/api/agent/*', delegationGuard(provider, {
+ *     getAgent: (req) => req.headers['x-agent-id'],
+ *     getAction: (req) => `${req.method} ${req.path}`,
+ *   }));
+ */
+function delegationGuard(provider, config) {
+    return async (req, res, next) => {
+        const agent = config.getAgent(req);
+        if (!agent) {
+            res.status(403).json({ error: "No agent identified in request" });
+            return;
+        }
+        const action = config.getAction(req);
+        const check = await provider.canAct(agent, action);
+        if (!check.allowed) {
+            res.status(403).json({
+                error: "Delegation check failed",
+                reason: check.reason,
+                agent,
+                action,
+            });
+            return;
+        }
+        await next();
+        // Log execution after success
+        provider
+            .logExecution(agent, action, check.agreement?.id, "success")
+            .catch(() => { });
+    };
+}

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,11 @@
 export { AgentCheckClient } from "./client";
 export { WebhookHandler } from "./webhook";
+export { DelegationProvider } from "./provider";
+export { delegationGuard } from "./guard";
+export { AgentToolChecker } from "./langchain";
+export { DelegationDashboard } from "./dashboard";
 export type { WebhookEvent } from "./webhook";
+export type { ScopeVerifier, DelegationProviderConfig } from "./provider";
+export type { GuardConfig } from "./guard";
 export { AgentCheckError, AuthenticationError, NotFoundError, ValidationError, RateLimitError, } from "./errors";
 export type { Agreement, AgreementList, SignupResult, WebhookResult, CreateRecordParams, ListParams, AmendParams, } from "./types";

package/dist/index.js CHANGED Viewed

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = exports.WebhookHandler = exports.AgentCheckClient = void 0;
+exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = 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; } });
 var webhook_1 = require("./webhook");
 Object.defineProperty(exports, "WebhookHandler", { enumerable: true, get: function () { return webhook_1.WebhookHandler; } });
+// Set menus (high-level wrappers)
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "DelegationProvider", { enumerable: true, get: function () { return provider_1.DelegationProvider; } });
+var guard_1 = require("./guard");
+Object.defineProperty(exports, "delegationGuard", { enumerable: true, get: function () { return guard_1.delegationGuard; } });
+var langchain_1 = require("./langchain");
+Object.defineProperty(exports, "AgentToolChecker", { enumerable: true, get: function () { return langchain_1.AgentToolChecker; } });
+var dashboard_1 = require("./dashboard");
+Object.defineProperty(exports, "DelegationDashboard", { enumerable: true, get: function () { return dashboard_1.DelegationDashboard; } });
 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/langchain.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import { DelegationProvider } from "./provider";
+/**
+ * AgentToolChecker - LangChain/CrewAI tool execution guard.
+ *
+ * Wraps a tool function to check delegation before execution.
+ *
+ * Usage:
+ *   const checker = new AgentToolChecker(provider, "my-bot");
+ *
+ *   // Wrap any tool
+ *   const safeTool = checker.wrap("send-email", originalSendEmail);
+ *   await safeTool({ to: "user@example.com", body: "Hello" });
+ *
+ *   // Or check manually
+ *   if (await checker.canUseTool("send-email")) { ... }
+ */
+export declare class AgentToolChecker {
+    private provider;
+    private agentName;
+    constructor(provider: DelegationProvider, agentName: string);
+    /** Check if agent can use a specific tool. */
+    canUseTool(toolName: string): Promise<boolean>;
+    /** Wrap a tool function with delegation check. */
+    wrap<T extends (...args: any[]) => Promise<any>>(toolName: string, toolFn: T): T;
+}

package/dist/langchain.js ADDED Viewed

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentToolChecker = void 0;
+/**
+ * AgentToolChecker - LangChain/CrewAI tool execution guard.
+ *
+ * Wraps a tool function to check delegation before execution.
+ *
+ * Usage:
+ *   const checker = new AgentToolChecker(provider, "my-bot");
+ *
+ *   // Wrap any tool
+ *   const safeTool = checker.wrap("send-email", originalSendEmail);
+ *   await safeTool({ to: "user@example.com", body: "Hello" });
+ *
+ *   // Or check manually
+ *   if (await checker.canUseTool("send-email")) { ... }
+ */
+class AgentToolChecker {
+    constructor(provider, agentName) {
+        this.provider = provider;
+        this.agentName = agentName;
+    }
+    /** Check if agent can use a specific tool. */
+    async canUseTool(toolName) {
+        const check = await this.provider.canAct(this.agentName, toolName);
+        return check.allowed;
+    }
+    /** Wrap a tool function with delegation check. */
+    wrap(toolName, toolFn) {
+        const self = this;
+        return (async (...args) => {
+            return self.provider.executeWithGuard(self.agentName, toolName, () => toolFn(...args));
+        });
+    }
+}
+exports.AgentToolChecker = AgentToolChecker;

package/dist/provider.d.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { AgentCheckClient } from "./client";
+import { Agreement } from "./types";
+export interface ScopeVerifier {
+    (scope: string, action: string, params?: Record<string, unknown>): boolean;
+}
+export interface DelegationProviderConfig {
+    /** Function to check if an action is within scope. You define the rules. */
+    verifyScope?: ScopeVerifier;
+}
+/**
+ * DelegationProvider - Universal set menu for AI agent delegation.
+ *
+ * Wraps individual SDK methods into high-level operations:
+ * - canAct(): "Can this agent do this action right now?"
+ * - hasActiveDelegation(): "Does this agent have any valid delegation?"
+ * - logExecution(): "Record what the agent actually did"
+ *
+ * Usage:
+ *   const provider = new DelegationProvider(client, {
+ *     verifyScope: (scope, action) => scope.includes(action),
+ *   });
+ *   if (await provider.canAct("my-bot", "send-email")) { ... }
+ */
+export declare class DelegationProvider {
+    private client;
+    private verifyScope;
+    constructor(client: AgentCheckClient, config?: DelegationProviderConfig);
+    /** Check if agent has valid delegation AND action is in scope. */
+    canAct(agentName: string, action: string, params?: Record<string, unknown>): Promise<{
+        allowed: boolean;
+        agreement?: Agreement;
+        reason?: string;
+    }>;
+    /** Check if agent has any active (approved) delegation. */
+    hasActiveDelegation(agentName: string): Promise<boolean>;
+    /** Log what an agent actually did (audit trail). */
+    logExecution(agentName: string, action: string, agreementId?: string, result?: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Full flow: check permission, execute, log. */
+    executeWithGuard<T>(agentName: string, action: string, executeFn: () => Promise<T>, params?: Record<string, unknown>): Promise<T>;
+}

package/dist/provider.js ADDED Viewed

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationProvider = void 0;
+/**
+ * DelegationProvider - Universal set menu for AI agent delegation.
+ *
+ * Wraps individual SDK methods into high-level operations:
+ * - canAct(): "Can this agent do this action right now?"
+ * - hasActiveDelegation(): "Does this agent have any valid delegation?"
+ * - logExecution(): "Record what the agent actually did"
+ *
+ * Usage:
+ *   const provider = new DelegationProvider(client, {
+ *     verifyScope: (scope, action) => scope.includes(action),
+ *   });
+ *   if (await provider.canAct("my-bot", "send-email")) { ... }
+ */
+class DelegationProvider {
+    constructor(client, config = {}) {
+        this.client = client;
+        this.verifyScope = config.verifyScope ?? (() => true);
+    }
+    /** Check if agent has valid delegation AND action is in scope. */
+    async canAct(agentName, action, params) {
+        const list = await this.client.list({ agent: agentName, status: "approved" });
+        if (!list.records.length) {
+            return { allowed: false, reason: "No active delegation" };
+        }
+        const agreement = list.records[0];
+        // Check expiry client-side (server also checks, but belt-and-suspenders)
+        if (agreement.expires_at && new Date(agreement.expires_at) < new Date()) {
+            return { allowed: false, reason: "Delegation expired", agreement };
+        }
+        // Check scope
+        if (!this.verifyScope(agreement.scope, action, params)) {
+            return { allowed: false, reason: "Action not in scope", agreement };
+        }
+        return { allowed: true, agreement };
+    }
+    /** Check if agent has any active (approved) delegation. */
+    async hasActiveDelegation(agentName) {
+        const list = await this.client.list({ agent: agentName, status: "approved" });
+        return list.records.length > 0;
+    }
+    /** Log what an agent actually did (audit trail). */
+    async logExecution(agentName, action, agreementId, result, metadata) {
+        await this.client.request("POST", "/api/v1/executions", {
+            agent: agentName,
+            action,
+            agreement_id: agreementId,
+            result,
+            metadata,
+        });
+    }
+    /** Full flow: check permission, execute, log. */
+    async executeWithGuard(agentName, action, executeFn, params) {
+        const check = await this.canAct(agentName, action, params);
+        if (!check.allowed) {
+            throw new Error(`Agent "${agentName}" cannot "${action}": ${check.reason}`);
+        }
+        const result = await executeFn();
+        await this.logExecution(agentName, action, check.agreement?.id, "success", params);
+        return result;
+    }
+}
+exports.DelegationProvider = DelegationProvider;

package/package.json CHANGED Viewed

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