agentverify 1.4.0 → 2.0.0

package/dist/guard.d.mts

@@ -0,0 +1,105 @@
+/**
+ * Agent Guard — runtime protection for AI agent tools.
+ *
+ *   import { createGuard } from 'agentverify/guard'
+ *   const guard = createGuard({
+ *     agent: 'support-bot',
+ *     policy: {
+ *       allow: ['lookup_order', 'send_email', 'refund'],
+ *       requireApproval: ['refund'],
+ *       args: { send_email: { to: { allowDomains: ['acme.com'] } } },
+ *       rateLimit: { perMinute: 30 },
+ *     },
+ *     approve: async call => askOnSlack(call),          // human-in-the-loop for risky tools
+ *     apiKey: process.env.AGENTVERIFY_API_KEY,           // optional: see every decision in the dashboard
+ *   })
+ *   const tools = guard.wrapAll({ lookup_order, send_email, refund })
+ *
+ * Every call to a wrapped tool is checked first. A blocked call throws GuardBlockedError (its message is safe to
+ * show the model), so a tricked or confused agent cannot take actions you did not allow.
+ */
+type ToolFn = (...args: any[]) => any;
+interface ArgRule {
+    /** Only these email domains / URL hosts are allowed in this argument (subdomains included). */
+    allowDomains?: string[];
+    /** Reject values longer than this (stops bulk data being pushed out through one argument). */
+    maxLength?: number;
+    /** Reject values matching this pattern. */
+    deny?: RegExp;
+}
+interface GuardPolicy {
+    /** Tools the agent may call. When set, every other tool is blocked. Supports '*' wildcards. */
+    allow?: Array<string | RegExp>;
+    /** Tools that are always blocked. Checked before allow. */
+    deny?: Array<string | RegExp>;
+    /** Tools that need a human yes before they run. */
+    requireApproval?: Array<string | RegExp>;
+    /** Per-tool argument rules, by argument name (for tools called with one object argument). */
+    args?: Record<string, Record<string, ArgRule>>;
+    /** Calls allowed across all tools. */
+    rateLimit?: {
+        perMinute?: number;
+        perRun?: number;
+    };
+    /** Block calls whose arguments contain an API key, token, or private key (the usual data-exfiltration path). Default true. */
+    blockSecrets?: boolean;
+    /** URL hosts any argument may point at. When set, URLs to other hosts are blocked. */
+    allowHosts?: string[];
+}
+interface ToolCall {
+    tool: string;
+    args: unknown[];
+    agent: string;
+}
+type Decision = 'allowed' | 'blocked' | 'approved' | 'rejected';
+interface GuardEvent {
+    agent: string;
+    tool: string;
+    decision: Decision;
+    reason: string;
+    at: string;
+    /** Argument preview with secrets masked and long values cut short. Never the full arguments. */
+    argsPreview: string;
+    durationMs?: number;
+}
+interface GuardOptions {
+    agent?: string;
+    policy: GuardPolicy;
+    /** Called for tools in requireApproval. Return true to let the call run. If missing, those calls are blocked. */
+    approve?: (call: ToolCall) => boolean | Promise<boolean>;
+    /** Called for every decision (e.g. to log locally). */
+    onEvent?: (event: GuardEvent) => void;
+    /** Send decisions to your Agent Verify dashboard. */
+    apiKey?: string;
+    apiUrl?: string;
+    /** Inject for tests. */
+    fetchFn?: typeof fetch;
+    now?: () => number;
+}
+declare class GuardBlockedError extends Error {
+    readonly tool: string;
+    readonly reason: string;
+    constructor(tool: string, reason: string);
+}
+declare function findSecret(value: unknown): string | null;
+/** A short, safe preview of the arguments for logs: secrets masked, values cut to 120 characters. */
+declare function previewArgs(args: unknown[]): string;
+/** The policy decision for one call, before any human approval. Exported for testing and dry runs. */
+declare function checkCall(policy: GuardPolicy, tool: string, args: unknown[]): {
+    ok: true;
+    needsApproval: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+interface Guard {
+    wrap<T extends ToolFn>(name: string, fn: T): T;
+    wrapAll<T extends Record<string, ToolFn>>(tools: T): T;
+    /** Send any queued events now (call before your process exits). */
+    flush(): Promise<void>;
+    /** Start a new run: resets the per-run call budget. */
+    newRun(): void;
+}
+declare function createGuard(options: GuardOptions): Guard;
+
+export { type ArgRule, type Decision, type Guard, GuardBlockedError, type GuardEvent, type GuardOptions, type GuardPolicy, type ToolCall, type ToolFn, checkCall, createGuard, findSecret, previewArgs };

package/dist/guard.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Agent Guard — runtime protection for AI agent tools.
+ *
+ *   import { createGuard } from 'agentverify/guard'
+ *   const guard = createGuard({
+ *     agent: 'support-bot',
+ *     policy: {
+ *       allow: ['lookup_order', 'send_email', 'refund'],
+ *       requireApproval: ['refund'],
+ *       args: { send_email: { to: { allowDomains: ['acme.com'] } } },
+ *       rateLimit: { perMinute: 30 },
+ *     },
+ *     approve: async call => askOnSlack(call),          // human-in-the-loop for risky tools
+ *     apiKey: process.env.AGENTVERIFY_API_KEY,           // optional: see every decision in the dashboard
+ *   })
+ *   const tools = guard.wrapAll({ lookup_order, send_email, refund })
+ *
+ * Every call to a wrapped tool is checked first. A blocked call throws GuardBlockedError (its message is safe to
+ * show the model), so a tricked or confused agent cannot take actions you did not allow.
+ */
+type ToolFn = (...args: any[]) => any;
+interface ArgRule {
+    /** Only these email domains / URL hosts are allowed in this argument (subdomains included). */
+    allowDomains?: string[];
+    /** Reject values longer than this (stops bulk data being pushed out through one argument). */
+    maxLength?: number;
+    /** Reject values matching this pattern. */
+    deny?: RegExp;
+}
+interface GuardPolicy {
+    /** Tools the agent may call. When set, every other tool is blocked. Supports '*' wildcards. */
+    allow?: Array<string | RegExp>;
+    /** Tools that are always blocked. Checked before allow. */
+    deny?: Array<string | RegExp>;
+    /** Tools that need a human yes before they run. */
+    requireApproval?: Array<string | RegExp>;
+    /** Per-tool argument rules, by argument name (for tools called with one object argument). */
+    args?: Record<string, Record<string, ArgRule>>;
+    /** Calls allowed across all tools. */
+    rateLimit?: {
+        perMinute?: number;
+        perRun?: number;
+    };
+    /** Block calls whose arguments contain an API key, token, or private key (the usual data-exfiltration path). Default true. */
+    blockSecrets?: boolean;
+    /** URL hosts any argument may point at. When set, URLs to other hosts are blocked. */
+    allowHosts?: string[];
+}
+interface ToolCall {
+    tool: string;
+    args: unknown[];
+    agent: string;
+}
+type Decision = 'allowed' | 'blocked' | 'approved' | 'rejected';
+interface GuardEvent {
+    agent: string;
+    tool: string;
+    decision: Decision;
+    reason: string;
+    at: string;
+    /** Argument preview with secrets masked and long values cut short. Never the full arguments. */
+    argsPreview: string;
+    durationMs?: number;
+}
+interface GuardOptions {
+    agent?: string;
+    policy: GuardPolicy;
+    /** Called for tools in requireApproval. Return true to let the call run. If missing, those calls are blocked. */
+    approve?: (call: ToolCall) => boolean | Promise<boolean>;
+    /** Called for every decision (e.g. to log locally). */
+    onEvent?: (event: GuardEvent) => void;
+    /** Send decisions to your Agent Verify dashboard. */
+    apiKey?: string;
+    apiUrl?: string;
+    /** Inject for tests. */
+    fetchFn?: typeof fetch;
+    now?: () => number;
+}
+declare class GuardBlockedError extends Error {
+    readonly tool: string;
+    readonly reason: string;
+    constructor(tool: string, reason: string);
+}
+declare function findSecret(value: unknown): string | null;
+/** A short, safe preview of the arguments for logs: secrets masked, values cut to 120 characters. */
+declare function previewArgs(args: unknown[]): string;
+/** The policy decision for one call, before any human approval. Exported for testing and dry runs. */
+declare function checkCall(policy: GuardPolicy, tool: string, args: unknown[]): {
+    ok: true;
+    needsApproval: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+interface Guard {
+    wrap<T extends ToolFn>(name: string, fn: T): T;
+    wrapAll<T extends Record<string, ToolFn>>(tools: T): T;
+    /** Send any queued events now (call before your process exits). */
+    flush(): Promise<void>;
+    /** Start a new run: resets the per-run call budget. */
+    newRun(): void;
+}
+declare function createGuard(options: GuardOptions): Guard;
+
+export { type ArgRule, type Decision, type Guard, GuardBlockedError, type GuardEvent, type GuardOptions, type GuardPolicy, type ToolCall, type ToolFn, checkCall, createGuard, findSecret, previewArgs };

package/dist/guard.js

@@ -0,0 +1,249 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/guard.ts
+var guard_exports = {};
+__export(guard_exports, {
+  GuardBlockedError: () => GuardBlockedError,
+  checkCall: () => checkCall,
+  createGuard: () => createGuard,
+  findSecret: () => findSecret,
+  previewArgs: () => previewArgs
+});
+module.exports = __toCommonJS(guard_exports);
+var GuardBlockedError = class extends Error {
+  constructor(tool, reason) {
+    super(`Blocked by Agent Verify Guard: "${tool}" \u2014 ${reason}. Do not retry this action; tell the user it needs permission.`);
+    this.name = "GuardBlockedError";
+    this.tool = tool;
+    this.reason = reason;
+  }
+};
+var SECRET_PATTERNS = [
+  /\bsk-(?:proj-|ant-)?[A-Za-z0-9_-]{20,}/,
+  /\bsk_(?:live|test)_[A-Za-z0-9]{16,}/,
+  /\bgh[pousr]_[A-Za-z0-9]{30,}/,
+  /\bgithub_pat_[A-Za-z0-9_]{40,}/,
+  /\bxox[abpr]-[A-Za-z0-9-]{10,}/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bAIza[0-9A-Za-z_-]{35}\b/,
+  /\bhf_[A-Za-z0-9]{30,}/,
+  /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/
+];
+function matches(name, patterns) {
+  return (patterns ?? []).some((p) => {
+    if (p instanceof RegExp) return p.test(name);
+    if (!p.includes("*")) return p === name;
+    const re = new RegExp(`^${p.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+    return re.test(name);
+  });
+}
+function strings(value, out = [], depth = 0) {
+  if (depth > 6 || out.length > 200) return out;
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) for (const v of value) strings(v, out, depth + 1);
+  else if (value && typeof value === "object") for (const v of Object.values(value)) strings(v, out, depth + 1);
+  return out;
+}
+function findSecret(value) {
+  for (const s of strings(value)) for (const re of SECRET_PATTERNS) if (re.test(s)) return re.source.slice(0, 24);
+  return null;
+}
+function hostAllowed(host, allowed) {
+  const h = host.toLowerCase();
+  return allowed.some((a) => {
+    const d = a.toLowerCase().replace(/^\*\./, "");
+    return h === d || h.endsWith(`.${d}`);
+  });
+}
+function urlsIn(value) {
+  const urls = [];
+  for (const s of strings(value)) {
+    for (const m of s.matchAll(/https?:\/\/[^\s"'<>]+/gi)) {
+      try {
+        urls.push(new URL(m[0]));
+      } catch {
+      }
+    }
+  }
+  return urls;
+}
+function previewArgs(args) {
+  const mask = (v) => {
+    if (typeof v === "string") {
+      let s = v;
+      for (const re of SECRET_PATTERNS) s = s.replace(new RegExp(re.source, "g"), (m) => `${m.slice(0, 4)}****`);
+      return s.length > 120 ? `${s.slice(0, 120)}\u2026` : s;
+    }
+    if (Array.isArray(v)) return v.slice(0, 10).map(mask);
+    if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).slice(0, 20).map(([k, x]) => [k, mask(x)]));
+    return v;
+  };
+  try {
+    const s = JSON.stringify(args.length === 1 ? mask(args[0]) : args.map(mask));
+    return (s ?? "").slice(0, 600);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function checkCall(policy, tool, args) {
+  if (matches(tool, policy.deny)) return { ok: false, reason: "this tool is on the deny list" };
+  if (policy.allow && !matches(tool, policy.allow)) return { ok: false, reason: "this tool is not on the allow list" };
+  if (policy.blockSecrets !== false) {
+    const secret = findSecret(args);
+    if (secret) return { ok: false, reason: "its arguments contain what looks like an API key or private key" };
+  }
+  if (policy.allowHosts?.length) {
+    const bad = urlsIn(args).find((u) => !hostAllowed(u.hostname, policy.allowHosts));
+    if (bad) return { ok: false, reason: `${bad.hostname} is not an allowed host` };
+  }
+  const rules = policy.args?.[tool];
+  const obj = args.length === 1 && args[0] && typeof args[0] === "object" ? args[0] : null;
+  if (rules && obj) {
+    for (const [name, rule] of Object.entries(rules)) {
+      const values = strings(obj[name]);
+      for (const v of values) {
+        if (rule.maxLength !== void 0 && v.length > rule.maxLength) return { ok: false, reason: `"${name}" is longer than ${rule.maxLength} characters` };
+        if (rule.deny && rule.deny.test(v)) return { ok: false, reason: `"${name}" matches a blocked pattern` };
+        if (rule.allowDomains?.length) {
+          const domains = [];
+          for (const m of v.matchAll(/@([A-Za-z0-9.-]+\.[A-Za-z]{2,})/g)) domains.push(m[1]);
+          for (const u of urlsIn(v)) domains.push(u.hostname);
+          if (domains.length === 0 && /@|:\/\//.test(v)) return { ok: false, reason: `"${name}" could not be checked against the allowed domains` };
+          const off = domains.find((d) => !hostAllowed(d, rule.allowDomains));
+          if (off) return { ok: false, reason: `"${name}" goes to ${off}, which is not an allowed domain` };
+        }
+      }
+    }
+  }
+  return { ok: true, needsApproval: matches(tool, policy.requireApproval) };
+}
+function createGuard(options) {
+  const agent = options.agent ?? "agent";
+  const now = options.now ?? Date.now;
+  const fetchFn = options.fetchFn ?? (typeof fetch === "function" ? fetch : void 0);
+  const apiUrl = (options.apiUrl ?? "https://agentverify-api.agentverify.workers.dev").replace(/\/v1\/scan$/, "");
+  const recent = [];
+  let runCalls = 0;
+  let queue = [];
+  let timer = null;
+  const send = async () => {
+    timer = null;
+    if (!queue.length || !options.apiKey || !fetchFn) {
+      queue = [];
+      return;
+    }
+    const batch = queue.splice(0, 100);
+    try {
+      await fetchFn(`${apiUrl}/v1/guard/events`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json", "User-Agent": "agentverify-guard/2.0.0" },
+        body: JSON.stringify({ events: batch })
+      });
+    } catch {
+    }
+    if (queue.length) await send();
+  };
+  const record = (event) => {
+    const full = { agent, at: new Date(now()).toISOString(), ...event };
+    try {
+      options.onEvent?.(full);
+    } catch {
+    }
+    if (options.apiKey) {
+      queue.push(full);
+      if (queue.length >= 50) void send();
+      else if (!timer) {
+        timer = setTimeout(() => void send(), 2e3);
+        timer.unref?.();
+      }
+    }
+  };
+  const overLimit = () => {
+    const t = now();
+    while (recent.length && recent[0] <= t - 6e4) recent.shift();
+    const perMinute = options.policy.rateLimit?.perMinute;
+    if (perMinute !== void 0 && recent.length >= perMinute) return `more than ${perMinute} tool calls in a minute`;
+    const perRun = options.policy.rateLimit?.perRun;
+    if (perRun !== void 0 && runCalls >= perRun) return `more than ${perRun} tool calls in this run`;
+    return null;
+  };
+  const wrap = (name, fn) => {
+    const guarded = async (...args) => {
+      const preview = previewArgs(args);
+      const limited = overLimit();
+      if (limited) {
+        record({ tool: name, decision: "blocked", reason: limited, argsPreview: preview });
+        throw new GuardBlockedError(name, limited);
+      }
+      const verdict = checkCall(options.policy, name, args);
+      if (!verdict.ok) {
+        record({ tool: name, decision: "blocked", reason: verdict.reason, argsPreview: preview });
+        throw new GuardBlockedError(name, verdict.reason);
+      }
+      let decision = "allowed";
+      if (verdict.needsApproval) {
+        let yes = false;
+        try {
+          yes = options.approve ? await options.approve({ tool: name, args, agent }) === true : false;
+        } catch {
+          yes = false;
+        }
+        if (!yes) {
+          const reason = options.approve ? "a person did not approve it" : "it needs human approval and no approver is set up";
+          record({ tool: name, decision: "rejected", reason, argsPreview: preview });
+          throw new GuardBlockedError(name, reason);
+        }
+        decision = "approved";
+      }
+      recent.push(now());
+      runCalls++;
+      const started = now();
+      try {
+        return await fn(...args);
+      } finally {
+        record({ tool: name, decision, reason: decision === "approved" ? "approved by a person" : "allowed by policy", argsPreview: preview, durationMs: now() - started });
+      }
+    };
+    Object.defineProperty(guarded, "name", { value: fn.name || name });
+    return guarded;
+  };
+  return {
+    wrap,
+    wrapAll(tools) {
+      return Object.fromEntries(Object.entries(tools).map(([k, f]) => [k, wrap(k, f)]));
+    },
+    async flush() {
+      if (timer) clearTimeout(timer);
+      await send();
+    },
+    newRun() {
+      runCalls = 0;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GuardBlockedError,
+  checkCall,
+  createGuard,
+  findSecret,
+  previewArgs
+});

package/dist/guard.mjs

@@ -0,0 +1,220 @@
+// src/guard.ts
+var GuardBlockedError = class extends Error {
+  constructor(tool, reason) {
+    super(`Blocked by Agent Verify Guard: "${tool}" \u2014 ${reason}. Do not retry this action; tell the user it needs permission.`);
+    this.name = "GuardBlockedError";
+    this.tool = tool;
+    this.reason = reason;
+  }
+};
+var SECRET_PATTERNS = [
+  /\bsk-(?:proj-|ant-)?[A-Za-z0-9_-]{20,}/,
+  /\bsk_(?:live|test)_[A-Za-z0-9]{16,}/,
+  /\bgh[pousr]_[A-Za-z0-9]{30,}/,
+  /\bgithub_pat_[A-Za-z0-9_]{40,}/,
+  /\bxox[abpr]-[A-Za-z0-9-]{10,}/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bAIza[0-9A-Za-z_-]{35}\b/,
+  /\bhf_[A-Za-z0-9]{30,}/,
+  /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/
+];
+function matches(name, patterns) {
+  return (patterns ?? []).some((p) => {
+    if (p instanceof RegExp) return p.test(name);
+    if (!p.includes("*")) return p === name;
+    const re = new RegExp(`^${p.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+    return re.test(name);
+  });
+}
+function strings(value, out = [], depth = 0) {
+  if (depth > 6 || out.length > 200) return out;
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) for (const v of value) strings(v, out, depth + 1);
+  else if (value && typeof value === "object") for (const v of Object.values(value)) strings(v, out, depth + 1);
+  return out;
+}
+function findSecret(value) {
+  for (const s of strings(value)) for (const re of SECRET_PATTERNS) if (re.test(s)) return re.source.slice(0, 24);
+  return null;
+}
+function hostAllowed(host, allowed) {
+  const h = host.toLowerCase();
+  return allowed.some((a) => {
+    const d = a.toLowerCase().replace(/^\*\./, "");
+    return h === d || h.endsWith(`.${d}`);
+  });
+}
+function urlsIn(value) {
+  const urls = [];
+  for (const s of strings(value)) {
+    for (const m of s.matchAll(/https?:\/\/[^\s"'<>]+/gi)) {
+      try {
+        urls.push(new URL(m[0]));
+      } catch {
+      }
+    }
+  }
+  return urls;
+}
+function previewArgs(args) {
+  const mask = (v) => {
+    if (typeof v === "string") {
+      let s = v;
+      for (const re of SECRET_PATTERNS) s = s.replace(new RegExp(re.source, "g"), (m) => `${m.slice(0, 4)}****`);
+      return s.length > 120 ? `${s.slice(0, 120)}\u2026` : s;
+    }
+    if (Array.isArray(v)) return v.slice(0, 10).map(mask);
+    if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).slice(0, 20).map(([k, x]) => [k, mask(x)]));
+    return v;
+  };
+  try {
+    const s = JSON.stringify(args.length === 1 ? mask(args[0]) : args.map(mask));
+    return (s ?? "").slice(0, 600);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function checkCall(policy, tool, args) {
+  if (matches(tool, policy.deny)) return { ok: false, reason: "this tool is on the deny list" };
+  if (policy.allow && !matches(tool, policy.allow)) return { ok: false, reason: "this tool is not on the allow list" };
+  if (policy.blockSecrets !== false) {
+    const secret = findSecret(args);
+    if (secret) return { ok: false, reason: "its arguments contain what looks like an API key or private key" };
+  }
+  if (policy.allowHosts?.length) {
+    const bad = urlsIn(args).find((u) => !hostAllowed(u.hostname, policy.allowHosts));
+    if (bad) return { ok: false, reason: `${bad.hostname} is not an allowed host` };
+  }
+  const rules = policy.args?.[tool];
+  const obj = args.length === 1 && args[0] && typeof args[0] === "object" ? args[0] : null;
+  if (rules && obj) {
+    for (const [name, rule] of Object.entries(rules)) {
+      const values = strings(obj[name]);
+      for (const v of values) {
+        if (rule.maxLength !== void 0 && v.length > rule.maxLength) return { ok: false, reason: `"${name}" is longer than ${rule.maxLength} characters` };
+        if (rule.deny && rule.deny.test(v)) return { ok: false, reason: `"${name}" matches a blocked pattern` };
+        if (rule.allowDomains?.length) {
+          const domains = [];
+          for (const m of v.matchAll(/@([A-Za-z0-9.-]+\.[A-Za-z]{2,})/g)) domains.push(m[1]);
+          for (const u of urlsIn(v)) domains.push(u.hostname);
+          if (domains.length === 0 && /@|:\/\//.test(v)) return { ok: false, reason: `"${name}" could not be checked against the allowed domains` };
+          const off = domains.find((d) => !hostAllowed(d, rule.allowDomains));
+          if (off) return { ok: false, reason: `"${name}" goes to ${off}, which is not an allowed domain` };
+        }
+      }
+    }
+  }
+  return { ok: true, needsApproval: matches(tool, policy.requireApproval) };
+}
+function createGuard(options) {
+  const agent = options.agent ?? "agent";
+  const now = options.now ?? Date.now;
+  const fetchFn = options.fetchFn ?? (typeof fetch === "function" ? fetch : void 0);
+  const apiUrl = (options.apiUrl ?? "https://agentverify-api.agentverify.workers.dev").replace(/\/v1\/scan$/, "");
+  const recent = [];
+  let runCalls = 0;
+  let queue = [];
+  let timer = null;
+  const send = async () => {
+    timer = null;
+    if (!queue.length || !options.apiKey || !fetchFn) {
+      queue = [];
+      return;
+    }
+    const batch = queue.splice(0, 100);
+    try {
+      await fetchFn(`${apiUrl}/v1/guard/events`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json", "User-Agent": "agentverify-guard/2.0.0" },
+        body: JSON.stringify({ events: batch })
+      });
+    } catch {
+    }
+    if (queue.length) await send();
+  };
+  const record = (event) => {
+    const full = { agent, at: new Date(now()).toISOString(), ...event };
+    try {
+      options.onEvent?.(full);
+    } catch {
+    }
+    if (options.apiKey) {
+      queue.push(full);
+      if (queue.length >= 50) void send();
+      else if (!timer) {
+        timer = setTimeout(() => void send(), 2e3);
+        timer.unref?.();
+      }
+    }
+  };
+  const overLimit = () => {
+    const t = now();
+    while (recent.length && recent[0] <= t - 6e4) recent.shift();
+    const perMinute = options.policy.rateLimit?.perMinute;
+    if (perMinute !== void 0 && recent.length >= perMinute) return `more than ${perMinute} tool calls in a minute`;
+    const perRun = options.policy.rateLimit?.perRun;
+    if (perRun !== void 0 && runCalls >= perRun) return `more than ${perRun} tool calls in this run`;
+    return null;
+  };
+  const wrap = (name, fn) => {
+    const guarded = async (...args) => {
+      const preview = previewArgs(args);
+      const limited = overLimit();
+      if (limited) {
+        record({ tool: name, decision: "blocked", reason: limited, argsPreview: preview });
+        throw new GuardBlockedError(name, limited);
+      }
+      const verdict = checkCall(options.policy, name, args);
+      if (!verdict.ok) {
+        record({ tool: name, decision: "blocked", reason: verdict.reason, argsPreview: preview });
+        throw new GuardBlockedError(name, verdict.reason);
+      }
+      let decision = "allowed";
+      if (verdict.needsApproval) {
+        let yes = false;
+        try {
+          yes = options.approve ? await options.approve({ tool: name, args, agent }) === true : false;
+        } catch {
+          yes = false;
+        }
+        if (!yes) {
+          const reason = options.approve ? "a person did not approve it" : "it needs human approval and no approver is set up";
+          record({ tool: name, decision: "rejected", reason, argsPreview: preview });
+          throw new GuardBlockedError(name, reason);
+        }
+        decision = "approved";
+      }
+      recent.push(now());
+      runCalls++;
+      const started = now();
+      try {
+        return await fn(...args);
+      } finally {
+        record({ tool: name, decision, reason: decision === "approved" ? "approved by a person" : "allowed by policy", argsPreview: preview, durationMs: now() - started });
+      }
+    };
+    Object.defineProperty(guarded, "name", { value: fn.name || name });
+    return guarded;
+  };
+  return {
+    wrap,
+    wrapAll(tools) {
+      return Object.fromEntries(Object.entries(tools).map(([k, f]) => [k, wrap(k, f)]));
+    },
+    async flush() {
+      if (timer) clearTimeout(timer);
+      await send();
+    },
+    newRun() {
+      runCalls = 0;
+    }
+  };
+}
+export {
+  GuardBlockedError,
+  checkCall,
+  createGuard,
+  findSecret,
+  previewArgs
+};

package/dist/sdk.d.mts

@@ -52,6 +52,10 @@ interface Finding {
     recommendedFix: string;
     fixCode?: string;
     quickFix?: string;
+    /** Line in the scanned content, when the finding can be located. */
+    line?: number;
+    /** Set by the API when this finding has a fix your plan does not include (Pro). */
+    fixLocked?: boolean;
     compliance?: {
         owasp?: string[];
         nist?: string[];