Capabilities

AgentGuard Spend evaluates five cap windows (per-call, per-minute, per-hour, per-day, per-month), four actions (allow, shadow, downgrade, block), one configured scope with six available dimensions, and four capability tiers. With signing keys configured, decisions are Ed25519-signed and SHA-256 hash-chained over deterministic key-sorted JSON.

tl;dr

One policy and one configured scope per guard. Four actions. Five cap windows. Four capability tiers. Three locales. Optional signed receipts. Three native provider interfaces. All policy evaluation runs in-process.

Capability	What you get
Cap windows	per_call per_minute per_hour per_day per_month Any combination. Each window has independent state. A single policy can carry a per-minute burst guard, a daily soft cap, and a monthly ceiling simultaneously.
Cap actions	allow: call passes; logged only shadow: call passes; decision recorded for analysis (no enforcement) downgrade: model parameter rewritten to a cheaper model, then call proceeds block: `AgentGuardBlockedError` raised before the provider is contacted
Scope dimensions	tenant → team → user → agent → task → provider These fields form one collision-resistant scope key for the guard's configured policy. To enforce separate team, user, or agent budgets, create guards or policies for those scopes. Within one policy, the most restrictive action among exceeded caps wins.
Capability gating	read_only < data_write < payment_initiate < payment_execute A policy can require a minimum capability tier. Calls without a sufficient `capabilityClaim` are blocked before the wrapped provider dispatch. Claims are caller-supplied unless the policy also requires a verified receipt-DAG attestation.
Localization	en-US es-419 Latin American Spanish pt-BR Brazilian Portuguese Block trace messages auto-detect the active locale via `AGENTGUARD_LOCALE`, `LC_ALL`, or system locale. Override explicitly with `locale="es-419"`.
Verification	When `config.signingKeys` is supplied, each decision produces an Ed25519-signed entry over deterministic key-sorted JSON. Anyone with the public key can verify the receipt without AgentGuard infrastructure. Without signing keys, enforcement still runs but the returned signed entry is `null`. Verify the latest local receipt: `agentguard verify`
Audit	Signed decision entries are hash-chained with SHA-256. Tampering with any field of any entry invalidates the chain from that point forward and is detectable during verification. The public package exports in-memory and NDJSON log stores; you can implement the `DecisionLogStore` interface for other storage.
Provider portability	Three native provider interfaces: OpenAI Anthropic Bedrock The OpenAI binding can also wrap compatible `chat.completions.create` clients, including OpenRouter-style endpoints. Anthropic Messages and Bedrock InvokeModel use their dedicated bindings.

Try it now

Install the Node package and run its deterministic local demo to produce and verify a real Ed25519-signed trace:

npm install -g @agentguard-run/spend
agentguard demo
agentguard verify

Core wrapper integration

Wrap an OpenAI-compatible client for local cap enforcement. Supply signing keys and a log store under config when you also want signed, persistent receipts:

import OpenAI from 'openai';
import { withSpendGuard } from '@agentguard-run/spend';

const client = withSpendGuard(new OpenAI(), {
  policy,
  scope: { tenantId: 'acme', agentId: 'agent-1' },
  config: { signingKeys, logStore }
});

The CLI commands

Command	What it does
`agentguard demo`	Deterministic simulation that produces the exact marketing block trace with a real Ed25519 signature over real canonical JSON. No network calls.
`agentguard verify`	Verify a signed receipt's Ed25519 signature + SHA-256 entry hash + chain link. Three green checkmarks = real cryptographic integrity.
`agentguard init`	Scaffolds `agentguard.policy.yaml` and `agentguard_quickstart.ts`, then adds `.agentguard/` to `.gitignore`. Existing files are preserved unless the explicit overwrite option is selected.
`agentguard doctor`	Health check: crypto backend, provider SDK detection, keypair directory writable, policy file present, dry-run block simulation. Green ✓ / red ✗ per item.
`agentguard explain <receipt>`	Pretty-prints a receipt: action, cap math step-by-step, what would unblock (and when), signature breakdown, policy context.

Security posture

Local core. Policy evaluation and receipt verification do not require an AgentGuard service.
No inference proxy. Prompts and provider API keys are not routed through AgentGuard infrastructure.
Optional control-plane calls. License validation, managed-key retrieval, consent verification, catalog sync, timestamp anchoring, and opt-in telemetry can use the network.
Signing is explicit. The wizard creates local Ed25519 keys; direct SDK users provide config.signingKeys.
Honors NO_COLOR=1 and AGENTGUARD_COLOR=0 for clean CI logs.
Telemetry is optional. The package implements enable, disable, and status controls; core enforcement does not depend on telemetry.

AgentGuard is patent-pending.