@backendkit-labs/aval-tools 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @backendkit-labs/aval-tools
+
+Herramientas de pago para agentes de `@backendkit-labs/agent-core` que gastan a través de una
+instancia de [AVAL](../../../../workspace-ideas/internet) — credencial por agente, presupuesto
+previo y bitácora encadenada.
+
+## Qué trae
+
+- **`pay`** — la vía amarrada: el agente pide un techo de gasto, AVAL decide y paga. Devuelve
+  el resultado como texto: pagado (con el coste real y la referencia del carril), retenido
+  (con el `authorizationId` para consultar después) o denegado (con el motivo).
+- **`check_payment`** — consulta el estado de una autorización propia por `authorizationId`.
+  Es la pieza que le faltaba al framework para la vía "retenido": nada bloquea una sesión
+  esperando a un humano, así que un gasto retenido se resuelve volviendo a preguntar más
+  tarde — en otra invocación, disparada por un trigger o por el propio usuario.
+
+Ninguna herramienta guarda dinero ni credenciales del proveedor: eso lo tiene AVAL.
+
+## Instalación
+
+```bash
+npm install @backendkit-labs/aval-tools
+```
+
+## Uso
+
+```ts
+import { AgentEngine, ToolRegistry } from '@backendkit-labs/agent-core';
+import { createAvalTools } from '@backendkit-labs/aval-tools';
+
+const tools = new ToolRegistry();
+for (const tool of createAvalTools({ baseUrl: 'https://aval.internal' })) {
+    tools.register(tool);
+}
+
+const profile = {
+    id: 'expedientes-bot',
+    // ...
+    allowedTools: ['pay', 'check_payment' /* ... */],
+    // La clave vive en el perfil de ESTE agente, no en una variable de entorno
+    // compartida por todos. Cárgala desde donde guardes secretos (vault,
+    // gestor de secretos del proveedor de nube, etc.), nunca en texto plano
+    // en un fichero que se vaya a commitear.
+    secrets: { AVAL_KEY: process.env.EXPEDIENTES_BOT_AVAL_KEY! },
+};
+```
+
+## Configuración
+
+```ts
+interface AvalToolsConfig {
+    baseUrl: string;       // dónde está AVAL
+    secretName?: string;   // nombre de la credencial en ctx.secrets — por defecto "AVAL_KEY"
+    timeoutMs?: number;    // por defecto 15000
+    maxAttempts?: number;  // por defecto 3
+}
+```
+
+## El flujo de un gasto retenido
+
+```
+1. El agente llama a pay("tarifas.aduana", 0.70, "Actualización trimestral").
+   → "Retenido para aprobación humana. authorizationId=auth_xyz. [...]"
+   El turno del agente termina ahí. No hace falta que la sesión siga viva.
+
+2. Horas después, alguien aprueba el gasto desde la consola de AVAL —
+   aprobar es pagar: AVAL usa su propia credencial, el agente no interviene.
+
+3. Una invocación nueva del agente (un cron, un webhook, o simplemente el
+   usuario preguntando "¿ya se aprobó eso?") llama a
+   check_payment("auth_xyz").
+   → "auth_xyz → liquidado — el pago se completó. [...]"
+```
+
+## Por qué reintentar no duplica el gasto
+
+`pay` deriva una clave de idempotencia a partir de la sesión y los argumentos exactos de la
+llamada (`sha256(sessionId:counterparty:ceiling:purpose)`). Un reintento del propio agente
+tras un timeout de red produce la misma clave y AVAL lo trata como una repetición, no como un
+segundo gasto. Una llamada genuinamente distinta —otro importe, otro propósito, otra sesión—
+obtiene una clave distinta por sí sola.
+
+## Qué pasa si AVAL no responde
+
+`pay` y `check_payment` reintentan automáticamente ante errores de red o 5xx (backoff
+exponencial con `jitter`, tres intentos por defecto). Los 4xx —denegado, credencial revocada,
+límite superado— nunca se reintentan: son respuestas de negocio, no fallos de transporte, y
+se devuelven al agente como texto para que decida qué hacer.

package/dist/__tests__/check-payment.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=check-payment.test.d.ts.map

package/dist/__tests__/check-payment.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-payment.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/check-payment.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/check-payment.test.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const check_payment_1 = require("../check-payment");
+function makeCtx(overrides = {}) {
+    return {
+        agentId: 'expedientes-bot',
+        sessionId: 'session-1',
+        memory: { get: () => undefined, set: () => undefined, getAll: () => ({}) },
+        askAgent: async () => '',
+        ...overrides,
+    };
+}
+function jsonResponse(status, body) {
+    return { status, ok: status >= 200 && status < 300, json: async () => body };
+}
+const config = { baseUrl: 'https://aval.test' };
+const checkPayment = (0, check_payment_1.createCheckPaymentTool)(config);
+beforeEach(() => {
+    global.fetch = jest.fn();
+});
+describe('check_payment', () => {
+    it('requires a credential before calling out', async () => {
+        const result = await checkPayment.execute({ authorizationId: 'auth_1' }, makeCtx());
+        expect(result).toMatch(/no tiene credencial de AVAL/);
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it('reports a resolved (settled) authorization', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(200, {
+            authorizationId: 'auth_2',
+            state: 'settled',
+            amount: 589500,
+            vendor: 'tarifas.aduana',
+            purpose: 'Padrón arancelario completo — trimestre',
+            rail: 'proxy',
+            reasons: ['Pagado por proxy: $0,5895.'],
+            createdAt: '2026-08-07T00:00:00.000Z',
+        }));
+        const result = await checkPayment.execute({ authorizationId: 'auth_2' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/liquidado/);
+        expect(result).toMatch(/\$0\.5895/); // 589500 micro-dollars, shown to sub-cent precision
+        expect(result).toMatch(/tarifas\.aduana/);
+    });
+    it('still shows "held" while nobody has decided yet', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(200, {
+            authorizationId: 'auth_3',
+            state: 'held',
+            amount: 700000,
+            vendor: 'tarifas.aduana',
+            purpose: 'Actualización trimestral',
+            rail: 'proxy',
+            reasons: [],
+            createdAt: '2026-08-07T00:00:00.000Z',
+        }));
+        const result = await checkPayment.execute({ authorizationId: 'auth_3' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/retenido/);
+        expect(result).toMatch(/todavía no se gastó nada/);
+    });
+    it('reports 404 as a plain not-found message, not a raw error', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(404, { error: 'No existe la autorización.' }));
+        const result = await checkPayment.execute({ authorizationId: 'auth_ghost' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/No existe/);
+    });
+    it('reports 403 as an ownership message when the authorization is not this agent\'s', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(403, { error: 'no es de este agente' }));
+        const result = await checkPayment.execute({ authorizationId: 'auth_other' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/no pertenece a este agente/);
+    });
+});
+//# sourceMappingURL=check-payment.test.js.map

package/dist/__tests__/check-payment.test.js.map

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

package/dist/__tests__/pay.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pay.test.d.ts.map

package/dist/__tests__/pay.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pay.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/pay.test.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const pay_1 = require("../pay");
+function makeCtx(overrides = {}) {
+    return {
+        agentId: 'expedientes-bot',
+        sessionId: 'session-1',
+        memory: { get: () => undefined, set: () => undefined, getAll: () => ({}) },
+        askAgent: async () => '',
+        ...overrides,
+    };
+}
+function jsonResponse(status, body) {
+    return { status, ok: status >= 200 && status < 300, json: async () => body };
+}
+const config = { baseUrl: 'https://aval.test' };
+const pay = (0, pay_1.createPayTool)(config);
+beforeEach(() => {
+    global.fetch = jest.fn();
+});
+describe('pay', () => {
+    it('rejects without touching the network when the agent has no AVAL credential', async () => {
+        const result = await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.3, purpose: 'test' }, makeCtx());
+        expect(result).toMatch(/no tiene credencial de AVAL/);
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it('sends the ceiling in micro-dollars and a bearer token from ctx.secrets', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(200, {
+            decision: 'authorized',
+            authorizationId: 'auth_1',
+            rail: 'proxy',
+            reasons: [],
+            capability: {
+                rail: 'proxy',
+                kind: 'respuesta',
+                actual: 280000,
+                payment: { rail: 'proxy', asset: 'USD', nativeAmount: 280000, rate: 1, ref: 'req_abc' },
+            },
+        }));
+        await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.3, purpose: 'Lectura del pedimento' }, makeCtx({ secrets: { AVAL_KEY: 'aval_sk_test_secret' } }));
+        const [url, init] = fetch.mock.calls[0];
+        expect(url).toBe('https://aval.test/api/v1/spend');
+        expect(init.headers.authorization).toBe('Bearer aval_sk_test_secret');
+        const body = JSON.parse(init.body);
+        expect(body.ceiling).toBe(300000); // $0.30 → 300000 micro-dollars
+        expect(body.counterparty).toBe('ocr.docs');
+        expect(typeof body.idempotencyKey).toBe('string');
+    });
+    it('derives the same idempotency key for the same session and args, a different one for different args', async () => {
+        fetch.mockResolvedValue(jsonResponse(200, { decision: 'denied', reasons: [] }));
+        const ctx = makeCtx({ secrets: { AVAL_KEY: 'k' } });
+        await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.3, purpose: 'A' }, ctx);
+        await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.3, purpose: 'A' }, ctx);
+        await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.31, purpose: 'A' }, ctx);
+        const keys = fetch.mock.calls.map(([, init]) => JSON.parse(init.body).idempotencyKey);
+        expect(keys[0]).toBe(keys[1]);
+        expect(keys[0]).not.toBe(keys[2]);
+    });
+    it('reports a held spend without claiming money moved', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(200, {
+            decision: 'held',
+            authorizationId: 'auth_2',
+            reasons: ['$0,70 supera el umbral de $0,60: requiere aprobación de María Restrepo.'],
+        }));
+        const result = await pay.execute({ counterparty: 'tarifas.aduana', ceilingUsd: 0.7, purpose: 'Padrón' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/Retenido/);
+        expect(result).toMatch(/auth_2/);
+        expect(result).toMatch(/check_payment/);
+        expect(result).not.toMatch(/Pagado/);
+    });
+    it('surfaces the denial reason instead of a raw error', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(200, { decision: 'denied', reasons: ['$0,90 supera el tope por operación de $0,80.'] }));
+        const result = await pay.execute({ counterparty: 'tarifas.aduana', ceilingUsd: 0.9, purpose: 'Descarga' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/Denegado/);
+        expect(result).toMatch(/tope por operación/);
+    });
+    it('surfaces rate limiting with the retry window', async () => {
+        fetch.mockResolvedValueOnce(jsonResponse(429, { error: 'Demasiados intentos.', retryAfterSeconds: 57 }));
+        const result = await pay.execute({ counterparty: 'ocr.docs', ceilingUsd: 0.1, purpose: 'x' }, makeCtx({ secrets: { AVAL_KEY: 'k' } }));
+        expect(result).toMatch(/57 s/);
+    });
+});
+//# sourceMappingURL=pay.test.js.map

package/dist/__tests__/pay.test.js.map

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

package/dist/check-payment.d.ts

@@ -0,0 +1,11 @@
+import { type AvalToolsConfig } from './client';
+/**
+ * Creates the `check_payment` tool: the other half of the async approval
+ * story. `pay` can return "retenido" and end the turn there — nothing in the
+ * framework blocks waiting for a human. This tool is how a later invocation
+ * (a cron trigger, a follow-up prompt, a human asking "¿ya se aprobó?") finds
+ * out what happened without needing the console credential AVAL's dashboard
+ * requires.
+ */
+export declare function createCheckPaymentTool(config: AvalToolsConfig): import("@backendkit-labs/agent-core").ToolDefinition;
+//# sourceMappingURL=check-payment.d.ts.map

package/dist/check-payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-payment.d.ts","sourceRoot":"","sources":["../src/check-payment.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAyBtE;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,wDAoC7D"}

package/dist/check-payment.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckPaymentTool = createCheckPaymentTool;
+const agent_core_1 = require("@backendkit-labs/agent-core");
+const client_1 = require("./client");
+const USD_PER_UNIT = 1_000_000;
+const usdFormat = new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 6 });
+const formatUsd = (units) => `$${usdFormat.format(units / USD_PER_UNIT)}`;
+const STATE_LABEL = {
+    held: 'retenido — esperando aprobación humana, todavía no se gastó nada',
+    authorized: 'autorizado — AVAL está pagando o ya pagó, aún sin confirmar el coste final',
+    settled: 'liquidado — el pago se completó',
+    released: 'liberado — se rechazó o falló, no se gastó nada',
+};
+/**
+ * Creates the `check_payment` tool: the other half of the async approval
+ * story. `pay` can return "retenido" and end the turn there — nothing in the
+ * framework blocks waiting for a human. This tool is how a later invocation
+ * (a cron trigger, a follow-up prompt, a human asking "¿ya se aprobó?") finds
+ * out what happened without needing the console credential AVAL's dashboard
+ * requires.
+ */
+function createCheckPaymentTool(config) {
+    return (0, agent_core_1.defineTool)({
+        name: 'check_payment',
+        description: 'Consulta el estado de un gasto pedido antes con pay, usando su authorizationId. ' +
+            'Úsalo para saber si un gasto "retenido" ya fue aprobado o rechazado.',
+        input: agent_core_1.z.object({
+            authorizationId: agent_core_1.z.string().describe('El authorizationId que devolvió pay.'),
+        }),
+        execute: async ({ authorizationId }, ctx) => {
+            const token = (0, client_1.avalKey)(config, ctx.secrets);
+            if (!token) {
+                return `Error: este agente no tiene credencial de AVAL configurada ` +
+                    `(falta ctx.secrets.${config.secretName ?? 'AVAL_KEY'} en su perfil).`;
+            }
+            const { status, body } = await (0, client_1.avalRequest)(config, token, 'GET', `/api/v1/spend/${encodeURIComponent(authorizationId)}`);
+            if (status === 404)
+                return `No existe ninguna autorización con id "${authorizationId}".`;
+            if (status === 403)
+                return `Esa autorización no pertenece a este agente.`;
+            if (status === 401)
+                return `Error de credencial: ${body.error}`;
+            if (!body.state)
+                return `Error: respuesta inesperada de AVAL (${status}): ${body.error ?? JSON.stringify(body)}`;
+            const reasons = body.reasons?.length ? `\nMotivo: ${body.reasons.join(' ')}` : '';
+            return (`${authorizationId} → ${STATE_LABEL[body.state]}.\n` +
+                `${formatUsd(body.amount)} · ${body.vendor}${body.rail ? ` · vía ${body.rail}` : ''} · ${body.purpose}` +
+                reasons);
+        },
+    });
+}
+//# sourceMappingURL=check-payment.js.map

package/dist/check-payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-payment.js","sourceRoot":"","sources":["../src/check-payment.ts"],"names":[],"mappings":";;AAkCA,wDAoCC;AAtED,4DAA4D;AAC5D,qCAAsE;AAEtE,MAAM,YAAY,GAAG,SAAS,CAAC;AAC/B,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,qBAAqB,EAAE,CAAC,EAAE,qBAAqB,EAAE,CAAC,EAAE,CAAC,CAAC;AACzG,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC;AAclF,MAAM,WAAW,GAAqD;IAClE,IAAI,EAAE,kEAAkE;IACxE,UAAU,EAAE,4EAA4E;IACxF,OAAO,EAAE,iCAAiC;IAC1C,QAAQ,EAAE,iDAAiD;CAC9D,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CAAC,MAAuB;IAC1D,OAAO,IAAA,uBAAU,EAAC;QACd,IAAI,EAAE,eAAe;QACrB,WAAW,EACP,kFAAkF;YAClF,sEAAsE;QAC1E,KAAK,EAAE,cAAC,CAAC,MAAM,CAAC;YACZ,eAAe,EAAE,cAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;SAC/E,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,EAAE,GAAG,EAAE,EAAE;YACxC,MAAM,KAAK,GAAG,IAAA,gBAAO,EAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACT,OAAO,6DAA6D;oBAChE,sBAAsB,MAAM,CAAC,UAAU,IAAI,UAAU,iBAAiB,CAAC;YAC/E,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAA,oBAAW,EACtC,MAAM,EACN,KAAK,EACL,KAAK,EACL,iBAAiB,kBAAkB,CAAC,eAAe,CAAC,EAAE,CACzD,CAAC;YAEF,IAAI,MAAM,KAAK,GAAG;gBAAE,OAAO,0CAA0C,eAAe,IAAI,CAAC;YACzF,IAAI,MAAM,KAAK,GAAG;gBAAE,OAAO,8CAA8C,CAAC;YAC1E,IAAI,MAAM,KAAK,GAAG;gBAAE,OAAO,wBAAwB,IAAI,CAAC,KAAK,EAAE,CAAC;YAChE,IAAI,CAAC,IAAI,CAAC,KAAK;gBAAE,OAAO,wCAAwC,MAAM,MAAM,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAEjH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,OAAO,CACH,GAAG,eAAe,MAAM,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK;gBACpD,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,OAAO,EAAE;gBACvG,OAAO,CACV,CAAC;QACN,CAAC;KACJ,CAAC,CAAC;AACP,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+export interface AvalToolsConfig {
+    /** Where AVAL is reachable, e.g. "https://aval.internal" or "http://localhost:3000". */
+    baseUrl: string;
+    /**
+     * Name of the credential inside ExecutionContext.secrets that holds this
+     * agent's AVAL key (aval_sk_… or a JWT). Defaults to "AVAL_KEY" so most
+     * callers never need to set this.
+     */
+    secretName?: string;
+    timeoutMs?: number;
+    maxAttempts?: number;
+}
+export interface AvalResponse<T> {
+    status: number;
+    ok: boolean;
+    body: T;
+}
+/**
+ * fetch() wrapper for AVAL, scoped to one call rather than one process: the
+ * bearer token is a parameter, not baked into the client, because it's the
+ * calling agent's own credential (ExecutionContext.secrets), not a shared
+ * process-wide key.
+ *
+ * Unlike a generic HTTP client, 4xx responses are NOT thrown here — AVAL's 400
+ * (denied), 401 (revoked/caducada), 403 (no es tuya), 404 (no existe) and 429
+ * (límite) are meaningful domain answers a tool has to turn into text an agent
+ * can act on, not transport failures. Only network errors and 5xx retry; only
+ * those, and a response body that isn't JSON, throw.
+ */
+export declare function avalRequest<T>(config: AvalToolsConfig, token: string, method: 'GET' | 'POST', path: string, body?: unknown): Promise<AvalResponse<T>>;
+/** Reads this agent's AVAL credential from its own secrets, never a shared env var. */
+export declare function avalKey(config: AvalToolsConfig, secrets: Record<string, string> | undefined): string | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC5B,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,CAAC,CAAC;CACX;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAC/B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAgD1B;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAE3G"}

package/dist/client.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.avalRequest = avalRequest;
+exports.avalKey = avalKey;
+const retry_1 = require("@backendkit-labs/retry");
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * fetch() wrapper for AVAL, scoped to one call rather than one process: the
+ * bearer token is a parameter, not baked into the client, because it's the
+ * calling agent's own credential (ExecutionContext.secrets), not a shared
+ * process-wide key.
+ *
+ * Unlike a generic HTTP client, 4xx responses are NOT thrown here — AVAL's 400
+ * (denied), 401 (revoked/caducada), 403 (no es tuya), 404 (no existe) and 429
+ * (límite) are meaningful domain answers a tool has to turn into text an agent
+ * can act on, not transport failures. Only network errors and 5xx retry; only
+ * those, and a response body that isn't JSON, throw.
+ */
+async function avalRequest(config, token, method, path, body) {
+    const url = `${config.baseUrl.replace(/\/$/, '')}${path}`;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const attempt = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${token}`,
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === 'AbortError';
+            // eslint-disable-next-line @typescript-eslint/no-throw-literal
+            throw {
+                type: 'network',
+                message: aborted
+                    ? `AVAL ${method} ${path} → timed out after ${timeoutMs}ms`
+                    : `AVAL ${method} ${path} → network error: ${err.message}`,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.status >= 500) {
+            // eslint-disable-next-line @typescript-eslint/no-throw-literal
+            throw { type: 'http', status: res.status, message: `AVAL ${method} ${path} → ${res.status}` };
+        }
+        const json = (await res.json().catch(() => ({})));
+        return { status: res.status, ok: res.ok, body: json };
+    };
+    const result = await (0, retry_1.retry)(attempt, {
+        maxAttempts: config.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+        backoff: { type: 'exponential', baseDelay: 500, maxDelay: 4_000, jitter: 'full' },
+        retryIf: (e) => e.type === 'network' || e.type === 'http',
+    });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return result.value;
+}
+/** Reads this agent's AVAL credential from its own secrets, never a shared env var. */
+function avalKey(config, secrets) {
+    return secrets?.[config.secretName ?? 'AVAL_KEY'] ?? null;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export type { AvalToolsConfig } from './client';
+export { avalKey, avalRequest } from './client';
+export { createPayTool } from './pay';
+export { createCheckPaymentTool } from './check-payment';
+import type { AvalToolsConfig } from './client';
+/**
+ * The two AVAL tools together, ready to spread into an agent's tool list.
+ *
+ * Wiring an agent up to AVAL is then: give the agent's profile a `secrets`
+ * entry with its AVAL key, add "pay" and "check_payment" to its
+ * `allowedTools`, and register these with the engine's ToolRegistry.
+ *
+ * @example
+ * ```ts
+ * import { createAvalTools } from '@backendkit-labs/aval-tools';
+ *
+ * const avalTools = createAvalTools({ baseUrl: 'https://aval.internal' });
+ * for (const tool of avalTools) tools.register(tool);
+ *
+ * const profile: AgentProfile = {
+ *   // ...
+ *   allowedTools: ['pay', 'check_payment', ...],
+ *   secrets: { AVAL_KEY: process.env.EXPEDIENTES_BOT_AVAL_KEY! },
+ * };
+ * ```
+ */
+export declare function createAvalTools(config: AvalToolsConfig): readonly [import("@backendkit-labs/agent-core").ToolDefinition, import("@backendkit-labs/agent-core").ToolDefinition];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,yHAEtD"}

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckPaymentTool = exports.createPayTool = exports.avalRequest = exports.avalKey = void 0;
+exports.createAvalTools = createAvalTools;
+const pay_1 = require("./pay");
+const check_payment_1 = require("./check-payment");
+var client_1 = require("./client");
+Object.defineProperty(exports, "avalKey", { enumerable: true, get: function () { return client_1.avalKey; } });
+Object.defineProperty(exports, "avalRequest", { enumerable: true, get: function () { return client_1.avalRequest; } });
+var pay_2 = require("./pay");
+Object.defineProperty(exports, "createPayTool", { enumerable: true, get: function () { return pay_2.createPayTool; } });
+var check_payment_2 = require("./check-payment");
+Object.defineProperty(exports, "createCheckPaymentTool", { enumerable: true, get: function () { return check_payment_2.createCheckPaymentTool; } });
+/**
+ * The two AVAL tools together, ready to spread into an agent's tool list.
+ *
+ * Wiring an agent up to AVAL is then: give the agent's profile a `secrets`
+ * entry with its AVAL key, add "pay" and "check_payment" to its
+ * `allowedTools`, and register these with the engine's ToolRegistry.
+ *
+ * @example
+ * ```ts
+ * import { createAvalTools } from '@backendkit-labs/aval-tools';
+ *
+ * const avalTools = createAvalTools({ baseUrl: 'https://aval.internal' });
+ * for (const tool of avalTools) tools.register(tool);
+ *
+ * const profile: AgentProfile = {
+ *   // ...
+ *   allowedTools: ['pay', 'check_payment', ...],
+ *   secrets: { AVAL_KEY: process.env.EXPEDIENTES_BOT_AVAL_KEY! },
+ * };
+ * ```
+ */
+function createAvalTools(config) {
+    return [(0, pay_1.createPayTool)(config), (0, check_payment_1.createCheckPaymentTool)(config)];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AA+BA,0CAEC;AAjCD,+BAAsC;AACtC,mDAAyD;AAGzD,mCAAgD;AAAvC,iGAAA,OAAO,OAAA;AAAE,qGAAA,WAAW,OAAA;AAC7B,6BAAsC;AAA7B,oGAAA,aAAa,OAAA;AACtB,iDAAyD;AAAhD,uHAAA,sBAAsB,OAAA;AAI/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,eAAe,CAAC,MAAuB;IACnD,OAAO,CAAC,IAAA,mBAAa,EAAC,MAAM,CAAC,EAAE,IAAA,sCAAsB,EAAC,MAAM,CAAC,CAAU,CAAC;AAC5E,CAAC"}

package/dist/pay.d.ts

@@ -0,0 +1,8 @@
+import { type AvalToolsConfig } from './client';
+/**
+ * Creates the `pay` tool: the amarrada path into AVAL. The agent asks for a
+ * ceiling; AVAL decides and, if authorized, pays through its own rail — the
+ * agent never sees a vendor credential to bypass.
+ */
+export declare function createPayTool(config: AvalToolsConfig): import("@backendkit-labs/agent-core").ToolDefinition;
+//# sourceMappingURL=pay.d.ts.map

package/dist/pay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../src/pay.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAuDtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,wDAuEpD"}

package/dist/pay.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPayTool = createPayTool;
+const node_crypto_1 = require("node:crypto");
+const agent_core_1 = require("@backendkit-labs/agent-core");
+const client_1 = require("./client");
+const USD_PER_UNIT = 1_000_000;
+/**
+ * A deterministic idempotency key from what the call actually is, not a
+ * random one: an agent that retries the exact same request after a timeout
+ * gets the exact same key and AVAL treats it as a replay instead of a second
+ * charge. A genuinely new request — different args, or a later turn — gets a
+ * different key on its own.
+ */
+function deriveIdempotencyKey(sessionId, counterparty, ceilingUsd, purpose) {
+    return (0, node_crypto_1.createHash)('sha256').update(`${sessionId}:${counterparty}:${ceilingUsd}:${purpose}`).digest('hex').slice(0, 24);
+}
+const usdFormat = new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 6 });
+/** Mirrors AVAL's own money() formatter: two decimals normally, up to six for sub-cent amounts. */
+function formatUsd(units) {
+    return `$${usdFormat.format(units / USD_PER_UNIT)}`;
+}
+/**
+ * Creates the `pay` tool: the amarrada path into AVAL. The agent asks for a
+ * ceiling; AVAL decides and, if authorized, pays through its own rail — the
+ * agent never sees a vendor credential to bypass.
+ */
+function createPayTool(config) {
+    return (0, agent_core_1.defineTool)({
+        name: 'pay',
+        description: 'Solicita un gasto a AVAL para pagar a una contraparte registrada. AVAL decide si se ' +
+            'autoriza, se retiene para aprobación humana, o se deniega, y si autoriza, paga él mismo ' +
+            'por el carril que corresponda. Nunca gastes por tu cuenta: si la respuesta no es ' +
+            '"authorized", no hay pago que hacer.',
+        input: agent_core_1.z.object({
+            counterparty: agent_core_1.z.string().describe('Identificador de la contraparte registrada en AVAL, p. ej. "ocr.docs".'),
+            ceilingUsd: agent_core_1.z.number().positive().describe('Techo del gasto en dólares, p. ej. 0.42 para 42 centavos. El coste real puede ser menor.'),
+            purpose: agent_core_1.z.string().describe('Motivo del gasto, en una frase clara: queda escrito en el registro de AVAL.'),
+            idempotencyKey: agent_core_1.z
+                .string()
+                .optional()
+                .describe('Sólo si necesitas forzar una clave concreta. Por defecto se deriva de la sesión y los argumentos.'),
+        }),
+        execute: async ({ counterparty, ceilingUsd, purpose, idempotencyKey }, ctx) => {
+            const token = (0, client_1.avalKey)(config, ctx.secrets);
+            if (!token) {
+                return `Error: este agente no tiene credencial de AVAL configurada ` +
+                    `(falta ctx.secrets.${config.secretName ?? 'AVAL_KEY'} en su perfil).`;
+            }
+            const ceiling = Math.round(ceilingUsd * USD_PER_UNIT);
+            const key = idempotencyKey ?? deriveIdempotencyKey(ctx.sessionId, counterparty, ceiling, purpose);
+            const { status, body } = await (0, client_1.avalRequest)(config, token, 'POST', '/api/v1/spend', {
+                counterparty,
+                ceiling,
+                purpose,
+                idempotencyKey: key,
+            });
+            if (status === 429) {
+                return `AVAL frenó la petición (demasiados intentos o llamadas). ` +
+                    `Reintenta en ${body.retryAfterSeconds ?? '?'} s. ${body.error ?? ''}`.trim();
+            }
+            if (status === 401 || status === 403) {
+                return `Error de credencial: ${body.error}`;
+            }
+            if (!body.decision) {
+                return `Error: respuesta inesperada de AVAL (${status}): ${body.error ?? JSON.stringify(body)}`;
+            }
+            const warning = body.credential?.warning ? `\nAviso de credencial: ${body.credential.warning}` : '';
+            const reasons = body.reasons?.length ? `\nMotivo: ${body.reasons.join(' ')}` : '';
+            if (body.decision === 'denied') {
+                return `Denegado.${reasons}${warning}`;
+            }
+            if (body.decision === 'held') {
+                return (`Retenido para aprobación humana. authorizationId="${body.authorizationId}".` +
+                    `${reasons}\nUsa check_payment con este authorizationId más tarde para saber si ya se resolvió — ` +
+                    `no se ha gastado nada todavía.${warning}`);
+            }
+            // authorized
+            const cap = body.capability;
+            const actual = cap ? formatUsd(cap.actual) : formatUsd(body.amount ?? ceiling);
+            const nativo = cap ? `${cap.payment.nativeAmount} ${cap.payment.asset}` : '';
+            return (`Pagado. authorizationId="${body.authorizationId}", carril=${body.rail ?? cap?.rail}, ` +
+                `coste real=${actual}${nativo ? ` (${nativo})` : ''}, ref=${cap?.payment.ref ?? '—'}.` +
+                `${reasons}${warning}`);
+        },
+    });
+}
+//# sourceMappingURL=pay.js.map

package/dist/pay.js.map

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

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@backendkit-labs/aval-tools",
+  "version": "0.1.0",
+  "description": "Payment tools for @backendkit-labs/agent-core agents to spend through an AVAL instance",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BackendKit-labs/backendkit-agent-framework.git",
+    "directory": "packages/aval-tools"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "*"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0"
+  }
+}