@agentguard-run/spend 0.1.0

package/dist/spend-guard.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * AgentGuard(TM) Spend — Core SDK entry point
+ *
+ * `withSpendGuard()` wraps a provider SDK client (OpenAI, Anthropic, Bedrock)
+ * and enforces a SpendPolicy locally before each call is sent to the provider.
+ *
+ * Design rule: ZERO DATA PLANE INVOLVEMENT.
+ *   - Prompts never leave the customer process.
+ *   - Provider API keys never leave the customer process.
+ *   - The signing key never leaves the customer process.
+ *   - All decisions and the entire signed log live in the customer's storage.
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * and an additional application filed May 2026).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentGuardBlockedError = exports.SpendGuard = void 0;
+exports.withSpendGuard = withSpendGuard;
+const policy_1 = require("./policy");
+const decision_log_1 = require("./decision-log");
+const store_memory_1 = require("./store-memory");
+const decision_log_2 = require("./decision-log");
+const cost_table_1 = require("./cost-table");
+class SpendGuard {
+    config;
+    spendStore;
+    logStore;
+    nextSequence = 0;
+    previousHash = decision_log_1.GENESIS_PREVIOUS_HASH;
+    constructor(config) {
+        this.config = config;
+        this.spendStore = config.spendStore ?? new store_memory_1.InMemorySpendStore();
+        this.logStore = config.logStore ?? new decision_log_2.InMemoryDecisionLogStore();
+    }
+    /**
+     * Hydrate the chain pointer from the log store. Call this once at startup
+     * if the log store is persistent and may already contain entries from a
+     * previous run.
+     */
+    async hydrate() {
+        const latest = await this.logStore.getLatest();
+        if (latest) {
+            this.nextSequence = latest.sequence + 1;
+            this.previousHash = latest.entryHash;
+        }
+    }
+    /**
+     * Evaluate the policy for a call and append to the decision log.
+     * Returns the decision plus the signed log entry (or null if unsigned).
+     */
+    async decide(call) {
+        const decision = await (0, policy_1.evaluatePolicy)(this.config.policy, call, this.spendStore);
+        let signed = null;
+        if (this.config.signingKeys) {
+            signed = await (0, decision_log_1.signDecision)({
+                sequence: this.nextSequence,
+                decision,
+                previousHash: this.previousHash,
+                privateKey: this.config.signingKeys.privateKey,
+                publicKey: this.config.signingKeys.publicKey,
+            });
+            await this.logStore.append(signed);
+            this.nextSequence += 1;
+            this.previousHash = signed.entryHash;
+        }
+        if (this.config.onDecision) {
+            await this.config.onDecision(decision, signed);
+        }
+        return { decision, signed };
+    }
+    /** Default token estimator: 1 token ≈ 4 characters of English. */
+    defaultTokenEstimator(text) {
+        return Math.ceil(text.length / 4);
+    }
+    /** Estimate tokens for a string using the configured estimator. */
+    estimateTokens(text) {
+        const fn = this.config.tokenEstimator ?? this.defaultTokenEstimator;
+        return fn(text);
+    }
+    /** Expose the spend store for tests and dashboards. */
+    getSpendStore() {
+        return this.spendStore;
+    }
+    /** Expose the log store for tests and dashboards. */
+    getLogStore() {
+        return this.logStore;
+    }
+}
+exports.SpendGuard = SpendGuard;
+class AgentGuardBlockedError extends Error {
+    decision;
+    constructor(decision) {
+        super(`AgentGuard Spend blocked call: policy='${decision.policyId}' ` +
+            `action='${decision.action}' reasons=${decision.reasons.join('; ')}`);
+        this.name = 'AgentGuardBlockedError';
+        this.decision = decision;
+    }
+}
+exports.AgentGuardBlockedError = AgentGuardBlockedError;
+/**
+ * Wrap an OpenAI client. Returns a proxy whose chat.completions.create
+ * enforces the spend policy. Other endpoints pass through untouched in this
+ * alpha; subsequent releases will cover responses, embeddings, and images.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withSpendGuard(client, opts) {
+    const guard = new SpendGuard({ policy: opts.policy, ...(opts.config ?? {}) });
+    const originalCreate = client?.chat?.completions?.create?.bind(client.chat.completions);
+    if (!originalCreate) {
+        throw new Error('withSpendGuard: expected an OpenAI client with chat.completions.create. ' +
+            'For Anthropic or Bedrock, use withAnthropicSpendGuard or withBedrockSpendGuard.');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.chat.completions.create = async (params) => {
+        const inputText = serializeMessages(params?.messages ?? []);
+        const inputTokens = guard.estimateTokens(inputText);
+        const outputTokens = typeof params?.max_tokens === 'number' ? params.max_tokens : 512;
+        const provider = (0, cost_table_1.inferProvider)(params?.model ?? '');
+        const call = {
+            provider,
+            model: params?.model ?? 'unknown',
+            inputTokens,
+            outputTokens,
+            scope: opts.scope,
+            capabilityClaim: opts.capabilityClaim,
+            label: params?.metadata?.label,
+        };
+        const { decision } = await guard.decide(call);
+        if (decision.action === 'block') {
+            throw new AgentGuardBlockedError(decision);
+        }
+        if (decision.action === 'downgrade' && decision.modelResolved !== decision.modelRequested) {
+            params = { ...params, model: decision.modelResolved };
+        }
+        // shadow + allow + downgrade all proceed to the provider.
+        return originalCreate(params);
+    };
+    // Attach the guard so callers can introspect or await hydration.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.__agentguard = guard;
+    return client;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function serializeMessages(messages) {
+    if (!Array.isArray(messages))
+        return '';
+    return messages
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .map((m) => (typeof m?.content === 'string' ? m.content : JSON.stringify(m?.content ?? '')))
+        .join('\n');
+}
+//# sourceMappingURL=spend-guard.js.map

package/dist/spend-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-guard.js","sourceRoot":"","sources":["../src/spend-guard.ts"],"names":[],"mappings":"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"}

package/dist/store-memory.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AgentGuard(TM) Spend — In-memory spend store
+ *
+ * Reference implementation of the SpendStore interface. Suitable for tests,
+ * examples, and single-process shadow deployments. Production callers with
+ * multi-process or distributed workloads should supply their own store
+ * (typically Redis with INCR, or Postgres with SELECT FOR UPDATE).
+ *
+ * Licensed under the alpha evaluation license; see LICENSE in the package
+ * root. Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * and an additional application filed May 2026).
+ */
+import type { SpendStore, SpendWindow } from './types';
+/**
+ * In-memory spend store. Thread-safe in single-process Node (we rely on the
+ * event loop's atomic execution between awaits; this store does no I/O).
+ */
+export declare class InMemorySpendStore implements SpendStore {
+    private state;
+    private key;
+    private rollIfStale;
+    getWindowSpend(scopeKey: string, window: SpendWindow): Promise<number>;
+    incrementWindowSpend(scopeKey: string, window: SpendWindow, cents: number): Promise<number>;
+    /** Clear all state. Test helper. */
+    reset(): void;
+}
+//# sourceMappingURL=store-memory.d.ts.map

package/dist/store-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-memory.d.ts","sourceRoot":"","sources":["../src/store-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA4BvD;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,KAAK,CAAkC;IAE/C,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,WAAW;IAYb,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtE,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC;IAMlB,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAGd"}

package/dist/store-memory.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * AgentGuard(TM) Spend — In-memory spend store
+ *
+ * Reference implementation of the SpendStore interface. Suitable for tests,
+ * examples, and single-process shadow deployments. Production callers with
+ * multi-process or distributed workloads should supply their own store
+ * (typically Redis with INCR, or Postgres with SELECT FOR UPDATE).
+ *
+ * Licensed under the alpha evaluation license; see LICENSE in the package
+ * root. Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * and an additional application filed May 2026).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemorySpendStore = void 0;
+const WINDOW_DURATION_MS = {
+    per_call: 0, // per_call windows reset on every read
+    per_minute: 60_000,
+    per_hour: 3_600_000,
+    per_day: 86_400_000,
+    per_month: 30 * 86_400_000, // approximate; production stores should use calendar-month boundaries
+};
+/**
+ * Returns the millisecond timestamp at which a window of the given duration
+ * containing `nowMs` started. For fixed-grid windows we align to UTC epoch
+ * (so all processes agree on window boundaries without coordination).
+ */
+function windowStart(window, nowMs) {
+    const dur = WINDOW_DURATION_MS[window];
+    if (dur === 0)
+        return nowMs; // per_call is trivial
+    return Math.floor(nowMs / dur) * dur;
+}
+/**
+ * In-memory spend store. Thread-safe in single-process Node (we rely on the
+ * event loop's atomic execution between awaits; this store does no I/O).
+ */
+class InMemorySpendStore {
+    state = new Map();
+    key(scopeKey, window) {
+        return `${scopeKey}::${window}`;
+    }
+    rollIfStale(scopeKey, window, nowMs) {
+        const k = this.key(scopeKey, window);
+        const expectedStart = windowStart(window, nowMs);
+        const existing = this.state.get(k);
+        if (!existing || existing.windowStartMs !== expectedStart) {
+            const fresh = { cents: 0, windowStartMs: expectedStart };
+            this.state.set(k, fresh);
+            return fresh;
+        }
+        return existing;
+    }
+    async getWindowSpend(scopeKey, window) {
+        const state = this.rollIfStale(scopeKey, window, Date.now());
+        return state.cents;
+    }
+    async incrementWindowSpend(scopeKey, window, cents) {
+        const state = this.rollIfStale(scopeKey, window, Date.now());
+        state.cents += cents;
+        return state.cents;
+    }
+    /** Clear all state. Test helper. */
+    reset() {
+        this.state.clear();
+    }
+}
+exports.InMemorySpendStore = InMemorySpendStore;
+//# sourceMappingURL=store-memory.js.map

package/dist/store-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-memory.js","sourceRoot":"","sources":["../src/store-memory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAWH,MAAM,kBAAkB,GAAgC;IACtD,QAAQ,EAAE,CAAC,EAAE,uCAAuC;IACpD,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,SAAS;IACnB,OAAO,EAAE,UAAU;IACnB,SAAS,EAAE,EAAE,GAAG,UAAU,EAAE,sEAAsE;CACnG,CAAC;AAEF;;;;GAIG;AACH,SAAS,WAAW,CAAC,MAAmB,EAAE,KAAa;IACrD,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,sBAAsB;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAa,kBAAkB;IACrB,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEvC,GAAG,CAAC,QAAgB,EAAE,MAAmB;QAC/C,OAAO,GAAG,QAAQ,KAAK,MAAM,EAAE,CAAC;IAClC,CAAC;IAEO,WAAW,CAAC,QAAgB,EAAE,MAAmB,EAAE,KAAa;QACtE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACrC,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,aAAa,KAAK,aAAa,EAAE,CAAC;YAC1D,MAAM,KAAK,GAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;YACtE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,QAAgB,EAAE,MAAmB;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,QAAgB,EAChB,MAAmB,EACnB,KAAa;QAEb,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7D,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;QACrB,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,oCAAoC;IACpC,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAtCD,gDAsCC"}

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * AgentGuard(TM) Spend — Core type definitions
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * and an additional application filed May 2026).
+ *
+ * Design rule: NO DATA PLANE INVOLVEMENT.
+ * All policy decisions are made locally in the customer runtime.
+ * Prompts, completions, and provider API keys never leave the customer process.
+ */
+export type SpendAction = 'block' | 'downgrade' | 'shadow' | 'allow';
+export type SpendWindow = 'per_call' | 'per_minute' | 'per_hour' | 'per_day' | 'per_month';
+export type Provider = 'openai' | 'anthropic' | 'bedrock' | 'gemini' | 'unknown';
+export type EnforcementMode = 'shadow' | 'canary' | 'enforce';
+export type CapabilityTier = 'read_only' | 'data_write' | 'payment_initiate' | 'payment_execute';
+/**
+ * A spend cap with one or more thresholds across configurable windows.
+ * All amounts are USD cents (integer math, no floating-point cost drift).
+ */
+export interface SpendCap {
+    /** Maximum cents spent in the given window before the action fires */
+    amountCents: number;
+    /** Time window over which the cap applies */
+    window: SpendWindow;
+    /** What to do when the cap is reached or projected to be reached */
+    action: SpendAction;
+    /** Optional model to downgrade to when action='downgrade' */
+    downgradeTo?: string;
+    /** Optional reason string included in decision log */
+    reason?: string;
+}
+/**
+ * Identity scope a cap applies to. Caps are matched on EVERY matching scope.
+ * If any scope's cap is exceeded, the most restrictive action wins.
+ */
+export interface SpendScope {
+    /** Tenant or organization ID. Required at top level. */
+    tenantId: string;
+    /** Optional user ID for per-user limits */
+    userId?: string;
+    /** Optional team ID */
+    teamId?: string;
+    /** Optional project / agent ID */
+    agentId?: string;
+    /** Optional task / job ID */
+    taskId?: string;
+    /** Optional provider scope (e.g., only enforce on OpenAI) */
+    provider?: Provider;
+}
+/**
+ * A full spend policy: name, scope, and ordered list of caps.
+ * The first cap whose threshold is reached determines the action.
+ */
+export interface SpendPolicy {
+    /** Stable identifier, e.g., 'finance-ops-v1' */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Scope this policy binds to */
+    scope: SpendScope;
+    /** Ordered list of caps (evaluated in order, first match wins) */
+    caps: SpendCap[];
+    /** Enforcement mode for graduated rollout */
+    mode: EnforcementMode;
+    /** Optional capability tier requirement.
+     *
+     * The tier set is informed by the capability-tier framework of Patent D
+     * §7.3 (App. No. 63/984,626). The SDK enforces a flat ordered comparison
+     * between the call's capability claim and this requirement. Sourcing the
+     * capability claim from a DAG-TAT verifier, an enterprise identity
+     * provider, an ERC-8004 credential, or any other attestation mechanism is
+     * out of scope of this package and is performed by the integrating code.
+     */
+    requiredCapability?: CapabilityTier;
+    /** Policy version, monotonically increasing */
+    version: number;
+    /** ISO 8601 effective-from timestamp */
+    effectiveFrom: string;
+}
+/**
+ * A single LLM call attempted under a policy.
+ */
+export interface CallContext {
+    /** Provider being called */
+    provider: Provider;
+    /** Model name as passed to the provider */
+    model: string;
+    /** Input token count (estimated or measured) */
+    inputTokens: number;
+    /** Output token count (estimated or measured) */
+    outputTokens: number;
+    /** Identity scope of the caller (must include tenantId) */
+    scope: SpendScope;
+    /** Optional human-readable label for the call */
+    label?: string;
+    /** Optional capability tier the caller claims */
+    capabilityClaim?: CapabilityTier;
+}
+/**
+ * The policy decision for a given call.
+ */
+export interface SpendDecision {
+    /** Unique decision ID (UUID v4) */
+    decisionId: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** The action taken */
+    action: SpendAction;
+    /** The cap that triggered the action, if any */
+    triggeredCap: SpendCap | null;
+    /** The scope key that the cap matched on */
+    triggeredScopeKey: string | null;
+    /** Cents the call would have cost */
+    projectedCents: number;
+    /** Cents spent in the relevant window before this call */
+    windowSpendBefore: number;
+    /** Cents that would be spent in the window after allowing this call */
+    windowSpendAfter: number;
+    /** Provider being called */
+    provider: Provider;
+    /** Model originally requested */
+    modelRequested: string;
+    /** Model actually used (differs from modelRequested on downgrade) */
+    modelResolved: string;
+    /** Policy ID and version this decision was made under */
+    policyId: string;
+    policyVersion: number;
+    /** Human-readable reasons */
+    reasons: string[];
+}
+/**
+ * A signed, hash-chained decision log entry.
+ *
+ * The chain enables tamper-evident audit: each entry binds the previous
+ * entry's hash, and the entire chain is verifiable with a public key.
+ *
+ * The capability-tier framework used here is informed by Patent D §7.3
+ * (App. No. 63/984,626). The flat tier comparison implemented in this SDK
+ * does not by itself implement the full DAG-TAT cryptographic gating of
+ * §7.3; integration with a DAG-TAT verifier is performed separately and
+ * is not required for the spend-governance functions of this package.
+ */
+export interface SignedDecisionLogEntry {
+    /** Monotonic chain sequence number (starts at 0) */
+    sequence: number;
+    /** The decision itself */
+    decision: SpendDecision;
+    /** SHA-256 hash of the previous entry, or 64 zeros for sequence=0 */
+    previousHash: string;
+    /** SHA-256 hash of this entry's canonical JSON (without signature) */
+    entryHash: string;
+    /** Ed25519 signature over entryHash, hex-encoded */
+    signature: string;
+    /** Hex-encoded public key fingerprint (first 8 bytes of SHA-256(pubkey)) */
+    signerFingerprint: string;
+}
+/**
+ * Storage backend for spend state. Implementations may use Redis, Postgres,
+ * SQLite, in-memory, or anything else. Spend state never leaves the customer
+ * runtime in the no-data-plane configuration.
+ */
+export interface SpendStore {
+    /**
+     * Get the total cents spent for a given scope key + window since the window start.
+     */
+    getWindowSpend(scopeKey: string, window: SpendWindow): Promise<number>;
+    /**
+     * Atomically increment the cents spent for a given scope key + window.
+     * Returns the new total. Implementations MUST be atomic to prevent races.
+     */
+    incrementWindowSpend(scopeKey: string, window: SpendWindow, cents: number): Promise<number>;
+}
+/**
+ * Storage backend for the signed decision log. Implementations may append to a
+ * local file, a database table, or any other append-only sink.
+ */
+export interface DecisionLogStore {
+    /** Append a new signed entry to the chain. */
+    append(entry: SignedDecisionLogEntry): Promise<void>;
+    /** Get the most recent entry, or null if empty. */
+    getLatest(): Promise<SignedDecisionLogEntry | null>;
+    /** Iterate from sequence onward (used by verification tools). */
+    read(fromSequence: number, limit: number): Promise<SignedDecisionLogEntry[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * AgentGuard(TM) Spend — Core type definitions
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * and an additional application filed May 2026).
+ *
+ * Design rule: NO DATA PLANE INVOLVEMENT.
+ * All policy decisions are made locally in the customer runtime.
+ * Prompts, completions, and provider API keys never leave the customer process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@agentguard-run/spend",
+  "version": "0.1.0",
+  "description": "Local-runtime spend caps and capability-gated model routing for AI agents. Prompts, API keys, and signing keys stay inside the customer runtime. Zero data plane involvement.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "require": "./dist/policy.js",
+      "import": "./dist/policy.mjs"
+    },
+    "./decision-log": {
+      "types": "./dist/decision-log.d.ts",
+      "require": "./dist/decision-log.js",
+      "import": "./dist/decision-log.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "PATENTS.md"
+  ],
+  "keywords": [
+    "ai-agent-security",
+    "spend-control",
+    "model-routing",
+    "local-first",
+    "no-proxy",
+    "tamper-evident",
+    "cryptographic-attestation",
+    "audit-log",
+    "agent-governance",
+    "ed25519",
+    "llm",
+    "ai-agents",
+    "policy-enforcement",
+    "openai",
+    "anthropic",
+    "bedrock"
+  ],
+  "author": "Dunecrest Ventures Inc. <hello@agentguard.run>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://agentguard.run",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MerchantGuardOps/agentguard-site"
+  },
+  "bugs": {
+    "url": "https://agentguard.run/contact"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.3.0"
+  },
+  "peerDependencies": {
+    "openai": ">=5.0.0",
+    "@anthropic-ai/sdk": ">=0.30.0",
+    "@aws-sdk/client-bedrock-runtime": ">=3.600.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": { "optional": true },
+    "@anthropic-ai/sdk": { "optional": true },
+    "@aws-sdk/client-bedrock-runtime": { "optional": true }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}