@agentguard-run/spend 0.1.3 → 0.1.6

package/README.es-419.md

@@ -0,0 +1,128 @@
+# @agentguard-run/spend
+
+> Límites de gasto de tiempo de ejecución local y enrutamiento de modelos con capacidades para agentes de IA.
+
+Cada decisión de política se ejecuta dentro de su proceso. Los prompts, claves API del proveedor y claves de firma nunca salen de su entorno de ejecución. Cada decisión de aplicación produce un recibo firmado con Ed25519, encadenado por hash, apto para auditoría y revisión de cumplimiento.
+
+> Disponible también en: [English](README.md) · [Português (BR)](README.pt-BR.md)
+
+## Por qué sin proxy
+
+Cada competidor financiado en gobernanza del gasto en IA (Portkey, Helicone, LiteLLM, Cloudflare AI Gateway, Vercel AI Gateway) usa proxy sobre su tráfico. Eso significa que sus prompts y claves de proveedor pasan por la infraestructura de ellos. `@agentguard-run/spend` nunca ve nada de eso. La política corre en su proceso. El registro firmado vive en su almacenamiento.
+
+## Instalación
+
+```bash
+npm install @agentguard-run/spend
+# o
+pnpm add @agentguard-run/spend
+# o
+yarn add @agentguard-run/spend
+```
+
+## Inicio rápido
+
+```ts
+import OpenAI from 'openai';
+import {
+  withSpendGuard,
+  AgentGuardBlockedError,
+  type SpendPolicy,
+} from '@agentguard-run/spend';
+import { randomBytes } from 'crypto';
+
+const policy: SpendPolicy = {
+  id: 'finance-ops-v1',
+  name: 'Límites diarios de operaciones financieras',
+  scope: { tenantId: 'acme-corp' },
+  caps: [
+    {
+      amountCents: 500,
+      window: 'per_day',
+      action: 'downgrade',
+      downgradeTo: 'gpt-4o-mini',
+      reason: 'Límite blando diario alcanzado, enrutando al modelo más económico',
+    },
+    {
+      amountCents: 2000,
+      window: 'per_day',
+      action: 'block',
+      reason: 'Tope diario duro',
+    },
+  ],
+  mode: 'enforce',
+  version: 1,
+  effectiveFrom: '2026-05-24T00:00:00Z',
+};
+
+const privateKey = new Uint8Array(randomBytes(32));
+
+const client = withSpendGuard(new OpenAI(), {
+  policy,
+  scope: { tenantId: 'acme-corp', agentId: 'finance-bot' },
+  config: {
+    policy,
+    signingKeys: {
+      privateKey,
+      publicKey: new Uint8Array(32),  // derivar de privateKey en producción
+    },
+    locale: 'es-419',  // opcional - también detecta automáticamente
+  },
+});
+
+try {
+  const completion = await client.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Hola' }],
+  });
+} catch (err) {
+  if (err instanceof AgentGuardBlockedError) {
+    // El mensaje será mostrado en español por el detector de locale
+    console.error(err.message);
+  }
+}
+```
+
+Cuando se dispara la política:
+
+| Acción      | Resultado                                                                          |
+|-------------|------------------------------------------------------------------------------------|
+| `allow`     | La llamada pasa sin modificaciones                                                 |
+| `downgrade` | El parámetro `model` se reescribe a `downgradeTo`, luego la llamada continúa       |
+| `block`     | Se lanza `AgentGuardBlockedError` antes de contactar al proveedor                  |
+| `shadow`    | La llamada pasa; la decisión se registra solo para análisis                        |
+
+## Localización (v0.1.4+)
+
+Los mensajes de bloqueo legibles están localizados en **inglés (en-US)**, **español de América Latina (es-419)** y **portugués brasileño (pt-BR)**. La resolución del locale sigue la cadena de prioridad estándar:
+
+1. Configuración explícita: `config: { locale: 'es-419', ... }`
+2. Variable de entorno: `export AGENTGUARD_LOCALE=es-419`
+3. Variables de entorno del sistema: `LC_ALL`, `LC_MESSAGES`, `LANG`
+4. `Intl.DateTimeFormat().resolvedOptions().locale` (navegador / Deno / Bun)
+5. Respaldo: `en-US`
+
+## Estado
+
+Vista previa privada. Diseñado para integración empresarial, OEM y de plataforma.
+
+Para acceso a evaluación, licencias OEM o consultas de asociación estratégica: `invest@agentguard.run`
+
+## Licencia y umbrales de uso
+
+El SDK es **gratuito** para:
+
+- Evaluación, prototipado y desarrollo no comercial a cualquier volumen
+- Despliegues de producción que procesan **hasta 10 000 llamadas de aplicación por mes calendario**
+
+Se requiere una licencia comercial separada para volúmenes mayores o redistribución. Consultas: `invest@agentguard.run`
+
+## Aviso de patentes
+
+Protegido por solicitudes de patente pendientes en EE. UU. (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626; 64/071,781; 64/071,789).
+
+## Enlaces
+
+- agentguard.run
+- Contacto: `invest@agentguard.run`
+- SDK Python: [`agentguard-spend`](https://pypi.org/project/agentguard-spend/)

package/README.md

@@ -2,6 +2,8 @@
 
 > Local-runtime spend caps and capability-gated model routing for AI agents.
 
+> Also available in: [Español (LATAM)](README.es-419.md) · [Português (BR)](README.pt-BR.md)
+
 Every policy decision runs inside your process. Prompts, provider API keys, and signing keys never leave your runtime. Each enforcement decision produces an Ed25519-signed, hash-chained receipt suitable for audit and compliance review.
 
 ## Why no proxy

package/README.pt-BR.md

@@ -0,0 +1,128 @@
+# @agentguard-run/spend
+
+> Limites de gasto em tempo de execução local e roteamento de modelos com capacidades para agentes de IA.
+
+Toda decisão de política é executada dentro do seu processo. Prompts, chaves de API do provedor e chaves de assinatura nunca saem do seu runtime. Cada decisão de aplicação produz um recibo assinado com Ed25519, encadeado por hash, adequado para auditoria e revisão de compliance.
+
+> Disponível também em: [English](README.md) · [Español (LATAM)](README.es-419.md)
+
+## Por que sem proxy
+
+Todo concorrente financiado em governança de gasto em IA (Portkey, Helicone, LiteLLM, Cloudflare AI Gateway, Vercel AI Gateway) faz proxy do seu tráfego. Isso significa que seus prompts e chaves de provedor passam pela infraestrutura deles. `@agentguard-run/spend` nunca vê nada disso. A política roda no seu processo. O log assinado vive no seu armazenamento.
+
+## Instalação
+
+```bash
+npm install @agentguard-run/spend
+# ou
+pnpm add @agentguard-run/spend
+# ou
+yarn add @agentguard-run/spend
+```
+
+## Quickstart
+
+```ts
+import OpenAI from 'openai';
+import {
+  withSpendGuard,
+  AgentGuardBlockedError,
+  type SpendPolicy,
+} from '@agentguard-run/spend';
+import { randomBytes } from 'crypto';
+
+const policy: SpendPolicy = {
+  id: 'finance-ops-v1',
+  name: 'Limites diários de operações financeiras',
+  scope: { tenantId: 'acme-corp' },
+  caps: [
+    {
+      amountCents: 500,
+      window: 'per_day',
+      action: 'downgrade',
+      downgradeTo: 'gpt-4o-mini',
+      reason: 'Limite leve diário atingido, redirecionando para modelo mais barato',
+    },
+    {
+      amountCents: 2000,
+      window: 'per_day',
+      action: 'block',
+      reason: 'Teto diário rígido',
+    },
+  ],
+  mode: 'enforce',
+  version: 1,
+  effectiveFrom: '2026-05-24T00:00:00Z',
+};
+
+const privateKey = new Uint8Array(randomBytes(32));
+
+const client = withSpendGuard(new OpenAI(), {
+  policy,
+  scope: { tenantId: 'acme-corp', agentId: 'finance-bot' },
+  config: {
+    policy,
+    signingKeys: {
+      privateKey,
+      publicKey: new Uint8Array(32),  // derivar de privateKey em produção
+    },
+    locale: 'pt-BR',  // opcional - também detecta automaticamente
+  },
+});
+
+try {
+  const completion = await client.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Olá' }],
+  });
+} catch (err) {
+  if (err instanceof AgentGuardBlockedError) {
+    // A mensagem será exibida em português pelo detector de locale
+    console.error(err.message);
+  }
+}
+```
+
+Quando a política dispara:
+
+| Ação        | Resultado                                                                                |
+|-------------|------------------------------------------------------------------------------------------|
+| `allow`     | A chamada passa sem alterações                                                           |
+| `downgrade` | O parâmetro `model` é reescrito para `downgradeTo`, então a chamada prossegue            |
+| `block`     | `AgentGuardBlockedError` é lançado antes de contatar o provedor                          |
+| `shadow`    | A chamada passa; a decisão é registrada apenas para análise                              |
+
+## Localização (v0.1.4+)
+
+Mensagens de bloqueio legíveis estão localizadas em **inglês (en-US)**, **espanhol latino-americano (es-419)** e **português brasileiro (pt-BR)**. A resolução do locale segue a cadeia de prioridade padrão:
+
+1. Configuração explícita: `config: { locale: 'pt-BR', ... }`
+2. Variável de ambiente: `export AGENTGUARD_LOCALE=pt-BR`
+3. Variáveis de ambiente do sistema: `LC_ALL`, `LC_MESSAGES`, `LANG`
+4. `Intl.DateTimeFormat().resolvedOptions().locale` (browser / Deno / Bun)
+5. Fallback: `en-US`
+
+## Status
+
+Preview privado. Projetado para integração corporativa, OEM e de plataforma.
+
+Para acesso de avaliação, licenciamento OEM ou consultas de parceria estratégica: `invest@agentguard.run`
+
+## Licença e limiares de uso
+
+O SDK é **gratuito** para:
+
+- Avaliação, prototipagem e desenvolvimento não comercial em qualquer volume
+- Implantações de produção processando **até 10.000 chamadas de aplicação por mês calendário**
+
+Uma licença comercial separada é necessária para volumes maiores ou redistribuição. Consultas: `invest@agentguard.run`
+
+## Aviso de patentes
+
+Protegido por aplicações de patente pendentes nos EUA (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626; 64/071,781; 64/071,789).
+
+## Links
+
+- agentguard.run
+- Contato: `invest@agentguard.run`
+- SDK Python: [`agentguard-spend`](https://pypi.org/project/agentguard-spend/)

package/bin/agentguard.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// AgentGuard CLI entry point (executable via `agentguard` after npm install).
+require('../dist/cli/main')
+  .main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/dist/cli/colors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ANSI color helpers with TTY detection.
+ *
+ * Honors:
+ *   - NO_COLOR=1                (industry standard; https://no-color.org)
+ *   - AGENTGUARD_COLOR=0        (product-specific opt-out)
+ *   - process.stdout.isTTY      (no color when piped to file or non-TTY)
+ */
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const cyan: (text: string) => string;
+export declare const brightRed: (text: string) => string;
+export declare const brightGreen: (text: string) => string;
+export declare const brightCyan: (text: string) => string;
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare function cyanBold(text: string): string;
+export declare function redBold(text: string): string;
+export declare function greenBold(text: string): string;
+export declare function banner(version: string): string;
+//# sourceMappingURL=colors.d.ts.map

package/dist/cli/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/cli/colors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,eAAO,MAAM,GAAG,SAJoB,MAAM,KAAK,MAIlB,CAAC;AAC9B,eAAO,MAAM,KAAK,SALkB,MAAM,KAAK,MAKhB,CAAC;AAChC,eAAO,MAAM,MAAM,SANiB,MAAM,KAAK,MAMf,CAAC;AACjC,eAAO,MAAM,IAAI,SAPmB,MAAM,KAAK,MAOjB,CAAC;AAC/B,eAAO,MAAM,SAAS,SARc,MAAM,KAAK,MAQZ,CAAC;AACpC,eAAO,MAAM,WAAW,SATY,MAAM,KAAK,MASV,CAAC;AACtC,eAAO,MAAM,UAAU,SAVa,MAAM,KAAK,MAUX,CAAC;AACrC,eAAO,MAAM,IAAI,SAXmB,MAAM,KAAK,MAWlB,CAAC;AAC9B,eAAO,MAAM,GAAG,SAZoB,MAAM,KAAK,MAYnB,CAAC;AAE7B,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/cli/colors.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * ANSI color helpers with TTY detection.
+ *
+ * Honors:
+ *   - NO_COLOR=1                (industry standard; https://no-color.org)
+ *   - AGENTGUARD_COLOR=0        (product-specific opt-out)
+ *   - process.stdout.isTTY      (no color when piped to file or non-TTY)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dim = exports.bold = exports.brightCyan = exports.brightGreen = exports.brightRed = exports.cyan = exports.yellow = exports.green = exports.red = void 0;
+exports.cyanBold = cyanBold;
+exports.redBold = redBold;
+exports.greenBold = greenBold;
+exports.banner = banner;
+function colorEnabled() {
+    if (typeof process === 'undefined')
+        return false;
+    if (process.env.NO_COLOR)
+        return false;
+    const ag = (process.env.AGENTGUARD_COLOR || '').toLowerCase();
+    if (['0', 'false', 'no', 'off'].includes(ag))
+        return false;
+    if (!process.stdout || !process.stdout.isTTY)
+        return false;
+    return true;
+}
+function wrap(code) {
+    return (text) => (colorEnabled() ? `\x1b[${code}m${text}\x1b[0m` : text);
+}
+exports.red = wrap('31');
+exports.green = wrap('32');
+exports.yellow = wrap('33');
+exports.cyan = wrap('36');
+exports.brightRed = wrap('91');
+exports.brightGreen = wrap('92');
+exports.brightCyan = wrap('96');
+exports.bold = wrap('1');
+exports.dim = wrap('2');
+function cyanBold(text) {
+    return colorEnabled() ? `\x1b[1;36m${text}\x1b[0m` : text;
+}
+function redBold(text) {
+    return colorEnabled() ? `\x1b[1;31m${text}\x1b[0m` : text;
+}
+function greenBold(text) {
+    return colorEnabled() ? `\x1b[1;32m${text}\x1b[0m` : text;
+}
+function banner(version) {
+    return cyanBold(`⬡ AGENTGUARD SPEND  ·  v${version}`);
+}
+//# sourceMappingURL=colors.js.map

package/dist/cli/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../src/cli/colors.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAyBH,4BAEC;AAED,0BAEC;AAED,8BAEC;AAED,wBAEC;AArCD,SAAS,YAAY;IACnB,IAAI,OAAO,OAAO,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9D,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,IAAI,CAAC,IAAY;IACxB,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACnF,CAAC;AAEY,QAAA,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACjB,QAAA,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACnB,QAAA,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACpB,QAAA,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AAClB,QAAA,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACvB,QAAA,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,QAAA,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,QAAA,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AACjB,QAAA,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AAE7B,SAAgB,QAAQ,CAAC,IAAY;IACnC,OAAO,YAAY,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAgB,OAAO,CAAC,IAAY;IAClC,OAAO,YAAY,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAgB,SAAS,CAAC,IAAY;IACpC,OAAO,YAAY,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAgB,MAAM,CAAC,OAAe;IACpC,OAAO,QAAQ,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/cli/demo.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `agentguard demo` — deterministic simulation with real cryptographic receipt.
+ *
+ * Output matches agentguard.run/the-block/ exactly. Dollar amounts and
+ * agent name are simulated parameters (fixed for reproducibility). The
+ * Ed25519 signature, SHA-256 chain hash, and canonical-JSON
+ * serialization are REAL — the receipt can be verified with
+ * `agentguard verify --trace latest`.
+ *
+ * No network calls. Fully offline. Deterministic across runs.
+ */
+export declare function runDemo(argv: string[]): Promise<number>;
+//# sourceMappingURL=demo.d.ts.map

package/dist/cli/demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../src/cli/demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuBH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmI7D"}

package/dist/cli/demo.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * `agentguard demo` — deterministic simulation with real cryptographic receipt.
+ *
+ * Output matches agentguard.run/the-block/ exactly. Dollar amounts and
+ * agent name are simulated parameters (fixed for reproducibility). The
+ * Ed25519 signature, SHA-256 chain hash, and canonical-JSON
+ * serialization are REAL — the receipt can be verified with
+ * `agentguard verify --trace latest`.
+ *
+ * No network calls. Fully offline. Deterministic across runs.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDemo = runDemo;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const ed = __importStar(require("@noble/ed25519"));
+const decision_log_1 = require("../decision-log");
+const i18n_1 = require("../i18n");
+const index_1 = require("../index");
+const colors_1 = require("./colors");
+const DEMO_HOME = path.join(os.homedir(), '.agentguard', 'demo');
+const DEMO_PRIVATE_KEY = path.join(DEMO_HOME, 'demo-private.key');
+const DEMO_PUBLIC_KEY = path.join(DEMO_HOME, 'demo-public.key');
+const DEMO_RECEIPT = path.join(DEMO_HOME, 'latest-receipt.json');
+async function runDemo(argv) {
+    if (argv.includes('--no-color')) {
+        process.env.NO_COLOR = '1';
+    }
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log('agentguard demo');
+        console.log('Run a deterministic simulation with a real cryptographic receipt.');
+        console.log('Options:');
+        console.log('  --no-color    Disable colored output (same as NO_COLOR=1).');
+        return 0;
+    }
+    // Simulated parameters - match the marketing screenshot at agentguard.run/the-block/.
+    const agentId = 'agent-finance-bot-v3';
+    const provider = 'anthropic';
+    const modelRequested = 'claude-opus-4-7';
+    const dailyCapCents = 50000; // $500.00
+    const projectedCents = 112241; // $1,122.41
+    const windowSpendBefore = 0;
+    const timestamp = '2026-05-24T18:00:00.000Z';
+    // Deterministic keypair from a fixed seed.
+    // Public + reproducible by design - NEVER use for production.
+    const privateSeed = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        privateSeed[i] = i;
+    const publicKey = await ed.getPublicKeyAsync(privateSeed);
+    const triggeredCap = {
+        amountCents: dailyCapCents,
+        window: 'per_day',
+        action: 'block',
+        reason: `Hard daily ceiling ($${(dailyCapCents / 100).toFixed(2)}/day)`,
+    };
+    const decision = {
+        decisionId: 'agentguard-demo-decision-v1',
+        timestamp,
+        policyId: 'agentguard-demo-policy-v1',
+        policyVersion: 1,
+        enforcementMode: 'enforce',
+        action: 'block',
+        reasons: [`Cap 'per_day=${dailyCapCents}c' exceeded`],
+        provider,
+        modelRequested,
+        modelResolved: modelRequested,
+        projectedCents,
+        windowSpendBefore,
+        windowSpendAfter: windowSpendBefore,
+        triggeredCap,
+        triggeredScopeKey: `tenantId=demo|agentId=${agentId}`,
+    };
+    // REAL Ed25519 signature over REAL canonical JSON.
+    const sequence = 0;
+    const previousHash = decision_log_1.GENESIS_PREVIOUS_HASH;
+    const entryHash = (0, decision_log_1.computeEntryHash)({ sequence, decision, previousHash });
+    void entryHash; // computed for the persisted receipt below
+    const signedEntry = await (0, decision_log_1.signDecision)({
+        sequence,
+        decision,
+        previousHash,
+        privateKey: privateSeed,
+        publicKey,
+    });
+    const signerFingerprint = (0, decision_log_1.computeSignerFingerprint)(publicKey);
+    console.log('');
+    console.log('  ' + (0, colors_1.banner)(index_1.AGENTGUARD_SPEND_VERSION));
+    console.log('');
+    console.log('  ' +
+        (0, colors_1.cyanBold)('AgentGuard Demo') +
+        (0, colors_1.dim)('  ·  ') +
+        (0, colors_1.dim)('[simulated transaction · real cryptographic receipt]'));
+    console.log('');
+    console.log((0, i18n_1.formatBlockedTrace)({
+        policyId: decision.policyId,
+        provider: decision.provider,
+        projectedCents: decision.projectedCents,
+        windowSpendBefore: decision.windowSpendBefore,
+        reasons: decision.reasons,
+        triggeredCap: { amountCents: triggeredCap.amountCents, window: triggeredCap.window },
+        agentId,
+    }));
+    console.log('');
+    // Persist the receipt so `agentguard verify --trace latest` works.
+    try {
+        fs.mkdirSync(DEMO_HOME, { recursive: true });
+        fs.writeFileSync(DEMO_PRIVATE_KEY, Buffer.from(privateSeed), { mode: 0o600 });
+        fs.writeFileSync(DEMO_PUBLIC_KEY, Buffer.from(publicKey));
+        fs.writeFileSync(DEMO_RECEIPT, JSON.stringify({
+            sequence,
+            entryHash,
+            previousHash,
+            signature: signedEntry.signature,
+            signerFingerprint,
+            publicKeyHex: Buffer.from(publicKey).toString('hex'),
+            decision,
+        }, null, 2));
+    }
+    catch {
+        // best-effort persist; demo still prints if disk write fails
+    }
+    const receiptId = entryHash.slice(0, 16);
+    console.log((0, colors_1.dim)('  ───────────────────────────────────────────'));
+    console.log(`  ${(0, colors_1.dim)('receipt   ')} ${receiptId}${(0, colors_1.dim)('...')}`);
+    console.log(`  ${(0, colors_1.dim)('signer    ')} ${signerFingerprint.slice(0, 16)}${(0, colors_1.dim)('...')}`);
+    console.log(`  ${(0, colors_1.dim)('sequence  ')} ${sequence}`);
+    console.log((0, colors_1.dim)('  ───────────────────────────────────────────'));
+    console.log('');
+    console.log('  ' +
+        (0, colors_1.green)('→') +
+        ' ' +
+        (0, colors_1.dim)('verify this receipt:') +
+        ' ' +
+        (0, colors_1.greenBold)('agentguard verify --trace latest'));
+    console.log('');
+    return 0;
+}
+//# sourceMappingURL=demo.js.map

package/dist/cli/demo.js.map

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

package/dist/cli/main.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AgentGuard CLI entry point.
+ *
+ * Usage:
+ *   agentguard demo                       Run a deterministic simulation
+ *   agentguard verify --trace latest      Verify the latest demo receipt
+ *   agentguard --version                  Show installed SDK version
+ *   agentguard --help                     Show this help
+ */
+export declare function main(argv?: string[]): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlF"}

package/dist/cli/main.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * AgentGuard CLI entry point.
+ *
+ * Usage:
+ *   agentguard demo                       Run a deterministic simulation
+ *   agentguard verify --trace latest      Verify the latest demo receipt
+ *   agentguard --version                  Show installed SDK version
+ *   agentguard --help                     Show this help
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const index_1 = require("../index");
+const HELP = `agentguard — local-runtime spend caps + signed receipts for AI agents
+
+usage:
+  agentguard <command> [options]
+
+commands:
+  demo              Run a deterministic simulation with a real cryptographic receipt.
+  verify            Verify a signed AgentGuard receipt.
+  --version         Show the installed SDK version.
+  --help            Show this help.
+
+examples:
+  agentguard demo
+  agentguard verify --trace latest
+
+docs:    https://agentguard.run
+install: pip install agentguard-spend  /  npm install @agentguard-run/spend
+`;
+async function main(argv = process.argv.slice(2)) {
+    if (argv.length === 0 || ['-h', '--help', 'help'].includes(argv[0])) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (['-v', '--version', 'version'].includes(argv[0])) {
+        console.log(`agentguard ${index_1.AGENTGUARD_SPEND_VERSION}`);
+        return 0;
+    }
+    const command = argv[0];
+    const rest = argv.slice(1);
+    if (command === 'demo') {
+        const { runDemo } = await Promise.resolve().then(() => __importStar(require('./demo')));
+        return runDemo(rest);
+    }
+    if (command === 'verify') {
+        const { runVerify } = await Promise.resolve().then(() => __importStar(require('./verify')));
+        return runVerify(rest);
+    }
+    process.stderr.write(`agentguard: unknown command '${command}'\n\n`);
+    process.stderr.write(HELP);
+    return 2;
+}
+// Allow `node dist/cli/main.js demo` directly
+if (require.main === module) {
+    main().then((code) => process.exit(code), (err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=main.js.map