@kya-brasil/agent-tools 0.1.0 → 0.2.0

package/README.md

@@ -29,11 +29,15 @@ const verdict = await kya.allowed(credentialId, {         // $0.01, signed
 if (!verdict.allowed) reject(verdict.reason);
 
 await verifyAttestation(verdict);                          // local Ed25519 check of the issuer's signature
+
+const receipt = await kya.registerAct(credentialId, {       // $0.02 once you accept it: signed receipt,
+  action: "order", amount: 4200, currency: "BRL", counterparty: "12345678000190", reference: "PO-1"
+});                                                          // daily ceilings enforced across counterparties
 ```
 
 Also check that the key that signed the agent's request is `v.agent.id`; the credential_id alone proves nothing.
 
-Agent frameworks (verifier tools `kya_verify`, `kya_check_action`, `kya_verify_paid`):
+Agent frameworks (verifier tools `kya_verify`, `kya_check_action`, `kya_register_act`, `kya_verify_paid`):
 
 ```ts
 import { toOpenAI, toVercelAI, toLangChain, toAnthropic } from "@kya-brasil/agent-tools";
@@ -52,7 +56,13 @@ const kya = createKyaClient({ privateKey: payerPk });
 const reg = await kya.register({                                           // $0.50
   agent: { kind: "evm", id: agentAddress },
   cnpj: "11.222.333/0001-81",
-  mandate: { actions: ["quote", "order", "pay"], max_per_operation: 5000, max_per_day: 20000, currencies: ["BRL", "USDC"] }
+  mandate: {
+    actions: ["quote", "order", "pay"],
+    max_per_operation: { amount: 5000, currency: "BRL" },
+    max_per_day: { amount: 20000, currency: "BRL" },
+    currencies: ["BRL"],
+    counterparties: ["12345678000190", "*.beta.com.br"]
+  }
 });
 
 const agent_signature = await signChallengeWithEvmKey(agentPk, reg.challenge.text);
@@ -78,6 +88,7 @@ Renew every 90 days (`kya.renew` then `kya.renewProve`), revoke at once (`kya.re
 |---|---|
 | verify, verifyByKey, prove, renewProve, revoke, revocations | free |
 | verified (signed receipt, no limit), allowed (signed verdict) | 0.01 |
+| registerAct (signed receipt of what the agent did) | 0.02 |
 | renew | 0.10 |
 | register | 0.50 |
 

package/dist/index.d.ts

@@ -8,15 +8,23 @@ export interface KyaOptions {
     internalKey?: string;
     fetch?: typeof fetch;
 }
+/** erc8004: id is eip155:<chainId>:<identityRegistry>:<agentId>; the on-chain agentWallet signs (credential.agent.wallet). */
 export type AgentKey = {
-    kind: "evm" | "web-bot-auth";
+    kind: "evm" | "web-bot-auth" | "erc8004";
     id: string;
+    wallet?: `0x${string}`;
 };
 export type CredentialStatus = "pending" | "active" | "suspended" | "revoked" | "expired";
 export interface Mandate {
     actions?: string[];
-    max_per_operation?: number;
-    max_per_day?: number;
+    max_per_operation?: {
+        amount: number;
+        currency: string;
+    };
+    max_per_day?: {
+        amount: number;
+        currency: string;
+    };
     currencies?: string[];
     counterparties?: string[];
     valid_from?: string;
@@ -123,6 +131,45 @@ export interface Proof {
     agent_signature: string;
     ecnpj_signature: string;
 }
+export interface ActInput {
+    action: string;
+    amount?: number;
+    currency?: string;
+    counterparty?: string;
+    reference?: string;
+    content_sha256?: string;
+    registered_by?: "counterparty" | "agent";
+    registrant?: string;
+    agent_signature?: string;
+}
+export interface ActReceipt {
+    act_id: string;
+    credential_id: string;
+    status: CredentialStatus;
+    allowed: boolean;
+    reason: string;
+    act: ActInput & {
+        agent_signed: boolean;
+    };
+    checks: {
+        rule: string;
+        ok: boolean;
+        detail?: string;
+    }[];
+    not_evaluated: string[];
+    spent_today_registered_before: {
+        currency: string;
+        amount: number;
+    } | null;
+    spent_today_registered_after: {
+        currency: string;
+        amount: number;
+    } | null;
+    registered_at: string;
+    receipt_url: string;
+    attestation?: Attestation;
+    [k: string]: unknown;
+}
 export declare class KyaError extends Error {
     readonly code: string;
     readonly status: number;
@@ -176,6 +223,27 @@ export interface KyaClient {
         credential_id: string;
         status: "revoked";
     }>;
+    /** $0.02: register what the agent did (you accepted it); mandate re-checked with today's registered acts; signed receipt. */
+    registerAct(credentialId: string, act: ActInput): Promise<ActReceipt>;
+    /** Free: a registered act and its receipt, by act_id. */
+    act(actId: string): Promise<ActReceipt>;
+    /** Free: the exact text the agent signs for an act (optional agent_signature). */
+    actText(credentialId: string, act: ActInput): Promise<{
+        credential_id: string;
+        agent: AgentKey;
+        text: string;
+    }>;
+    /** Free, company only: the trail of an agent's acts, request signed with the e-CNPJ over actsExportText(id). */
+    exportActs(credentialId: string, input: {
+        signed_text: string;
+        ecnpj_signature: string;
+        since?: string;
+    }): Promise<{
+        credential_id: string;
+        since: string;
+        count: number;
+        acts: Record<string, unknown>[];
+    }>;
     /** Free: credentials revoked since a date (default 30 days). */
     revocations(since?: string): Promise<{
         since: string;
@@ -248,6 +316,8 @@ export interface ECnpjMaterial {
  * Works with A1 certificates (file). A3 (token or smart card) must sign through the vendor's software.
  */
 export declare function signWithECnpj(material: ECnpjMaterial, text: string): Promise<string>;
+/** The text the company signs to read its agent's trail of acts. */
+export declare function actsExportText(credentialId: string, nonce?: string): string;
 /** The text the company signs to revoke a credential. */
 export declare function revocationText(credentialId: string, nonce?: string): string;
 export interface VerifyResult {

package/dist/index.js

@@ -80,6 +80,10 @@ export function createKyaClient(opts = {}) {
         renewProve: (id, proof) => call("POST", `/v1/agents/${encodeURIComponent(id)}/renew/prove`, proof),
         revoke: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/revoke`, input),
         revocations: (since) => call("GET", `/v1/revocations${q({ since })}`),
+        registerAct: (id, act) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts`, act, true, 0.02),
+        act: (actId) => call("GET", `/v1/acts/${encodeURIComponent(actId)}`),
+        actText: (id, act) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts/text`, act),
+        exportActs: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts/export`, input),
         tools: [],
         execute: async (name, args) => {
             const t = client.tools.find((x) => x.name === name);
@@ -93,7 +97,7 @@ export function createKyaClient(opts = {}) {
         {
             name: "kya_verify", priceUsd: 0,
             description: "Free. Is this AI agent credentialed by a Brazilian company? Returns the credential (company CNPJ and name, mandate, KYB snapshot), its live status (active, suspended, revoked, expired) and history. Give credential_id, or the agent key (kind + id) to look it up.",
-            parameters: { type: "object", properties: { credential_id: ID, kind: { type: "string", enum: ["evm", "web-bot-auth"] }, id: { type: "string", description: "0x address or base64url Ed25519 key" } }, additionalProperties: false },
+            parameters: { type: "object", properties: { credential_id: ID, kind: { type: "string", enum: ["evm", "web-bot-auth", "erc8004"] }, id: { type: "string", description: "0x address, base64url Ed25519 key, or eip155:<chainId>:<registry>:<agentId>" } }, additionalProperties: false },
             execute: async (a) => (a.credential_id ? client.verify(String(a.credential_id)) : client.verifyByKey({ kind: a.kind, id: String(a.id) }))
         },
         {
@@ -102,6 +106,12 @@ export function createKyaClient(opts = {}) {
             parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "Your CNPJ, domain or wallet address" }, spent_today: { type: "number" } }, required: ["credential_id"], additionalProperties: false },
             execute: async (a) => client.allowed(String(a.credential_id), { action: a.action, amount: a.amount, currency: a.currency, counterparty: a.counterparty, spent_today: a.spent_today })
         },
+        {
+            name: "kya_register_act", priceUsd: 0.02,
+            description: "Register an action you accepted from an agent ($0.02): the issuer re-checks the mandate including everything registered today by anyone (so daily ceilings hold across counterparties) and returns a signed receipt, your proof of what the agent could and did do. Denied acts are recorded too.",
+            parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "You: CNPJ, domain or wallet" }, reference: { type: "string" }, content_sha256: { type: "string" } }, required: ["credential_id", "action"], additionalProperties: false },
+            execute: async (a) => { const { credential_id, ...act } = a; return client.registerAct(String(credential_id), act); }
+        },
         {
             name: "kya_verify_paid", priceUsd: 0.01,
             description: "Same as kya_verify without the daily limit, plus a signed receipt of the verification ($0.01).",
@@ -163,6 +173,10 @@ export async function signWithECnpj(material, text) {
         s += String.fromCharCode(b);
     return btoa(s);
 }
+/** The text the company signs to read its agent's trail of acts. */
+export function actsExportText(credentialId, nonce = crypto.randomUUID()) {
+    return `KYA Brasil: acts ${credentialId}\n${nonce}`;
+}
 /** The text the company signs to revoke a credential. */
 export function revocationText(credentialId, nonce = crypto.randomUUID()) {
     return `KYA Brasil: revoke ${credentialId}\n${nonce}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed, KYB-checked credential), check an action against its mandate, or give your own agent a credential. x402 payments (USDC on Base) handled for you. Adapters for Vercel AI SDK, LangChain, OpenAI and Anthropic.",
   "license": "MIT",
   "type": "module",