@x1id/resolve 0.22.0 → 0.43.0

package/dist/agent.js

@@ -24,6 +24,8 @@
  * that reports a level shares one vocabulary.
  */
 import { X1_TESTNET_NETWORK, X1_MAINNET_NETWORK } from "./x402.js";
+import { paymentAddressFor } from "./payment.js";
+import { CHAIN_COIN_TYPE } from "./types.js";
 // ---------------------------------------------------------------------------
 // Well-known text-record keys
 // ---------------------------------------------------------------------------
@@ -38,9 +40,33 @@ export const AGENT_RECORD_KEYS = Object.freeze({
     attestation: "agent.attestation",
     capabilities: "agent.capabilities",
 });
+/** Manifest versions {@link validateManifest} accepts. v1 is the original
+ *  shape; v2 (`docs/agent-records.md` §3.1) adds per-capability / per-endpoint
+ *  pricing, accepted payment methods and a name-bound `payTo`. A v1 manifest
+ *  validates exactly as it always did. */
+export const AGENT_MANIFEST_VERSIONS = Object.freeze([1, 2]);
+/** Billing units a v2 price may use. `per-call` is the x402 "exact" unit; the
+ *  rest are metered units the seller's live 402 quotes per request. */
+export const AGENT_PRICE_UNITS = Object.freeze([
+    "per-call",
+    "per-1k-tokens",
+    "per-1k-chars",
+    "per-minute",
+    "per-mb",
+]);
+/** The native-asset sentinel for {@link AgentPrice.mint}: XNT on X1. */
+export const AGENT_NATIVE_MINT = "XNT";
 const HTTPS_RE = /^https:\/\/[^\s@/]+(\/[^\s]*)?$/;
 const IPFS_RE = /^ipfs:\/\/[^\s]+$/;
 const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const EVM_ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+/** v2 id grammar (capability / endpoint / method ids): a lowercase slug. */
+export const AGENT_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const CAIP2_RE = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$/;
+const U64_MAX = 18446744073709551615n;
+const MAX_V2_CAPABILITIES = 64;
+const MAX_V2_METHODS = 8;
+const MAX_V2_PRICES = 8;
 /** URL rule (`docs/agent-records.md` §2): every URL field is `https://`
  *  ONLY, except `agent.manifest`'s own record value, which may also be
  *  `ipfs://<cid>` (`allowIpfs`). */
@@ -64,7 +90,8 @@ export function validateManifest(raw, opts) {
     if (typeof x1id !== "object" || x1id === null) {
         return { ok: false, errors: [{ code: "missing-field", field: "x1id" }] };
     }
-    if (x1id.version !== 1)
+    const version = x1id.version;
+    if (version !== 1 && version !== 2)
         errors.push({ code: "bad-version" });
     if (x1id.name !== opts.expectedName)
         errors.push({ code: "name-mismatch" });
@@ -89,7 +116,11 @@ export function validateManifest(raw, opts) {
     }
     const capabilities = m.capabilities;
     if (capabilities !== undefined) {
-        if (typeof capabilities.url !== "string" || !checkAgentUrl(capabilities.url, false)) {
+        // v1: `url` is required. v2: `url` OR `items` (a manifest may list its
+        // capabilities inline instead of pointing at a separate document).
+        const urlOptional = version === 2 && capabilities.items !== undefined;
+        if (!(urlOptional && capabilities.url === undefined) &&
+            (typeof capabilities.url !== "string" || !checkAgentUrl(capabilities.url, false))) {
             errors.push({ code: "bad-url", field: "capabilities.url" });
         }
         if (capabilities.schema !== undefined &&
@@ -128,11 +159,325 @@ export function validateManifest(raw, opts) {
             }
         }
     }
+    if (version === 2)
+        validateV2(m, x1id, errors);
     if (errors.length > 0)
         return { ok: false, errors };
     return { ok: true, manifest: raw };
 }
 // ---------------------------------------------------------------------------
+// v2: pricing, payment methods, name-bound payTo
+// ---------------------------------------------------------------------------
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** `amount` is a u64 decimal string of smallest units (no sign, no decimal
+ *  point, no leading zeros except "0"). */
+function checkAmount(v) {
+    if (typeof v !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(v))
+        return false;
+    return BigInt(v) <= U64_MAX;
+}
+/** A price/asset mint spelling: the native sentinel, an SVM mint, or (CDP
+ *  rail only) an EVM token address. */
+function checkMint(v) {
+    return typeof v === "string" && (v === AGENT_NATIVE_MINT || BASE58_RE.test(v) || EVM_ADDR_RE.test(v));
+}
+function checkPrices(raw, field, errors, out) {
+    if (raw === undefined)
+        return;
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_V2_PRICES) {
+        errors.push({ code: "bad-field", field });
+        return;
+    }
+    for (const p of raw) {
+        if (!isObj(p)) {
+            errors.push({ code: "bad-price", field });
+            continue;
+        }
+        if (!checkAmount(p.amount))
+            errors.push({ code: "bad-price", field: `${field}[].amount` });
+        if (!checkMint(p.mint))
+            errors.push({ code: "bad-price", field: `${field}[].mint` });
+        if (typeof p.unit !== "string" || !AGENT_PRICE_UNITS.includes(p.unit)) {
+            errors.push({ code: "bad-price", field: `${field}[].unit` });
+        }
+        if (checkAmount(p.amount) && checkMint(p.mint))
+            out.push(p);
+    }
+}
+/** Expected X1 x402 network id for a manifest's declared cluster. */
+function x1NetworkFor(cluster) {
+    return cluster === "testnet" ? X1_TESTNET_NETWORK : X1_MAINNET_NETWORK;
+}
+/** Does `method` settle `mint`? An explicit `assets` list is authoritative;
+ *  otherwise the x1 rail settles XNT or any SPL mint, and the cdp rail
+ *  anything but native XNT. */
+function methodSettles(method, mint) {
+    if (method.assets)
+        return method.assets.includes(mint);
+    if (method.rail === "x1")
+        return mint === AGENT_NATIVE_MINT || BASE58_RE.test(mint);
+    return mint !== AGENT_NATIVE_MINT;
+}
+function validateV2(m, x1id, errors) {
+    const prices = [];
+    // endpoints[]: optional id (unique), capabilities[] refs, pricing[].
+    const endpointIds = new Set();
+    const endpointCapRefs = [];
+    if (m.endpoints !== undefined && !Array.isArray(m.endpoints))
+        errors.push({ code: "bad-field", field: "endpoints" });
+    const endpoints = Array.isArray(m.endpoints) ? m.endpoints : [];
+    endpoints.forEach((e) => {
+        if (!isObj(e))
+            return;
+        if (e.id !== undefined) {
+            if (typeof e.id !== "string" || !AGENT_ID_RE.test(e.id))
+                errors.push({ code: "bad-id", field: "endpoints[].id" });
+            else if (endpointIds.has(e.id))
+                errors.push({ code: "duplicate-id", field: "endpoints[].id", id: e.id });
+            else
+                endpointIds.add(e.id);
+        }
+        if (e.capabilities !== undefined) {
+            if (!Array.isArray(e.capabilities) || e.capabilities.length > MAX_V2_CAPABILITIES) {
+                errors.push({ code: "bad-field", field: "endpoints[].capabilities" });
+            }
+            else {
+                for (const c of e.capabilities) {
+                    if (typeof c !== "string" || !AGENT_ID_RE.test(c))
+                        errors.push({ code: "bad-id", field: "endpoints[].capabilities[]" });
+                    else
+                        endpointCapRefs.push(c);
+                }
+            }
+        }
+        checkPrices(e.pricing, "endpoints[].pricing", errors, prices);
+    });
+    // capabilities.items[]: id (unique), description, endpoint ref, pricing[].
+    const capIds = new Set();
+    const caps = isObj(m.capabilities) ? m.capabilities : undefined;
+    const items = caps?.items;
+    if (items !== undefined) {
+        if (!Array.isArray(items) || items.length > MAX_V2_CAPABILITIES) {
+            errors.push({ code: "bad-field", field: "capabilities.items" });
+        }
+        else {
+            for (const it of items) {
+                if (!isObj(it)) {
+                    errors.push({ code: "bad-field", field: "capabilities.items[]" });
+                    continue;
+                }
+                if (typeof it.id !== "string" || !AGENT_ID_RE.test(it.id)) {
+                    errors.push({ code: "bad-id", field: "capabilities.items[].id" });
+                }
+                else if (capIds.has(it.id)) {
+                    errors.push({ code: "duplicate-id", field: "capabilities.items[].id", id: it.id });
+                }
+                else
+                    capIds.add(it.id);
+                if (it.description !== undefined && (typeof it.description !== "string" || it.description.length > 512)) {
+                    errors.push({ code: "bad-field", field: "capabilities.items[].description" });
+                }
+                if (it.endpoint !== undefined) {
+                    if (typeof it.endpoint !== "string" || !AGENT_ID_RE.test(it.endpoint)) {
+                        errors.push({ code: "bad-id", field: "capabilities.items[].endpoint" });
+                    }
+                    else if (!endpointIds.has(it.endpoint)) {
+                        errors.push({ code: "unknown-endpoint", id: it.endpoint });
+                    }
+                }
+                checkPrices(it.pricing, "capabilities.items[].pricing", errors, prices);
+            }
+        }
+    }
+    // An endpoint's capability refs must exist when the manifest lists items
+    // inline. (Without items, endpoint tags are free-standing search tags.)
+    if (Array.isArray(items)) {
+        for (const ref of new Set(endpointCapRefs))
+            if (!capIds.has(ref))
+                errors.push({ code: "unknown-capability", id: ref });
+    }
+    // payment.payTo / payment.methods.
+    const payment = isObj(m.payment) ? m.payment : undefined;
+    const payTo = payment?.payTo;
+    if (payTo !== undefined) {
+        if (!isObj(payTo) || Object.keys(payTo).some((k) => k !== "name")) {
+            errors.push({ code: "free-form-payto" });
+        }
+        else if (typeof payTo.name !== "string" || payTo.name.replace(/^@/, "") !== x1id.name) {
+            errors.push({ code: "payto-name-mismatch" });
+        }
+    }
+    const methods = [];
+    const rawMethods = payment?.methods;
+    if (rawMethods !== undefined) {
+        if (!Array.isArray(rawMethods) || rawMethods.length === 0 || rawMethods.length > MAX_V2_METHODS) {
+            errors.push({ code: "bad-field", field: "payment.methods" });
+        }
+        else {
+            const ids = new Set();
+            for (const pm of rawMethods) {
+                if (!isObj(pm)) {
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[]" });
+                    continue;
+                }
+                let ok = true;
+                if (pm.id !== undefined) {
+                    if (typeof pm.id !== "string" || !AGENT_ID_RE.test(pm.id)) {
+                        errors.push({ code: "bad-id", field: "payment.methods[].id" });
+                        ok = false;
+                    }
+                    else if (ids.has(pm.id)) {
+                        errors.push({ code: "duplicate-id", field: "payment.methods[].id", id: pm.id });
+                    }
+                    else
+                        ids.add(pm.id);
+                }
+                if (pm.type !== "x402") {
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[].type" });
+                    ok = false;
+                }
+                if (pm.rail !== "x1" && pm.rail !== "cdp") {
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[].rail" });
+                    ok = false;
+                }
+                if (typeof pm.network !== "string" || !CAIP2_RE.test(pm.network)) {
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[].network" });
+                    ok = false;
+                }
+                else if (pm.rail === "x1" && pm.network !== x1NetworkFor(x1id.network)) {
+                    // The X1-native rail settles on THIS manifest's cluster only.
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[].network" });
+                    ok = false;
+                }
+                if (pm.scheme !== undefined && pm.scheme !== "exact") {
+                    errors.push({ code: "bad-payment-method", field: "payment.methods[].scheme" });
+                    ok = false;
+                }
+                if (pm.facilitator !== undefined && (typeof pm.facilitator !== "string" || !checkAgentUrl(pm.facilitator, false))) {
+                    errors.push({ code: "bad-url", field: "payment.methods[].facilitator" });
+                    ok = false;
+                }
+                if (pm.assets !== undefined) {
+                    if (!Array.isArray(pm.assets) || pm.assets.length === 0 || pm.assets.length > 16 || !pm.assets.every(checkMint)) {
+                        errors.push({ code: "bad-payment-method", field: "payment.methods[].assets" });
+                        ok = false;
+                    }
+                    else if (pm.rail === "x1" && pm.assets.some((a) => EVM_ADDR_RE.test(a))) {
+                        errors.push({ code: "bad-payment-method", field: "payment.methods[].assets" });
+                        ok = false;
+                    }
+                }
+                if (ok)
+                    methods.push(pm);
+            }
+        }
+    }
+    // Anything priced ⇒ a name-bound payTo AND at least one method that
+    // settles each priced mint.
+    if (prices.length > 0) {
+        if (payTo === undefined)
+            errors.push({ code: "missing-payto" });
+        if (rawMethods === undefined)
+            errors.push({ code: "missing-payment-method" });
+        else if (methods.length > 0) {
+            for (const mint of new Set(prices.map((p) => p.mint))) {
+                if (!methods.some((pm) => methodSettles(pm, mint)))
+                    errors.push({ code: "unsupported-price-mint", mint });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// v2 readers — capability ids, offers, name-bound payTo resolution
+// ---------------------------------------------------------------------------
+/** Every capability id a (validated) manifest advertises: v2 `items[].id`
+ *  plus endpoint tags, deduped, in first-seen order. `[]` for v1. Used by the
+ *  directory to index capability search. */
+export function manifestCapabilities(manifest) {
+    if (manifest.x1id.version !== 2)
+        return [];
+    const out = new Set();
+    for (const it of manifest.capabilities?.items ?? [])
+        out.add(it.id);
+    for (const e of manifest.endpoints ?? [])
+        for (const c of e.capabilities ?? [])
+            out.add(c);
+    return [...out];
+}
+/** Flatten a v2 manifest's prices into offers. `[]` for v1. */
+export function manifestOffers(manifest) {
+    if (manifest.x1id.version !== 2)
+        return [];
+    const byId = new Map();
+    for (const e of manifest.endpoints ?? [])
+        if (e.id)
+            byId.set(e.id, e);
+    const out = [];
+    for (const it of manifest.capabilities?.items ?? []) {
+        const ep = it.endpoint ? byId.get(it.endpoint) : undefined;
+        for (const price of it.pricing ?? []) {
+            out.push({ capability: it.id, endpoint: it.endpoint ?? null, url: ep?.url ?? null, endpointType: ep?.type ?? null, price });
+        }
+    }
+    for (const e of manifest.endpoints ?? []) {
+        for (const price of e.pricing ?? []) {
+            out.push({ capability: null, endpoint: e.id ?? null, url: e.url, endpointType: e.type, price });
+        }
+    }
+    return out;
+}
+/** The chain a payment method settles on, for the W16 rule. `null` = a
+ *  network the rule cannot resolve (the method is then flagged unpayable). */
+export function paymentMethodChain(method) {
+    if (method.rail === "x1")
+        return "X1";
+    if (method.network === X1_TESTNET_NETWORK || method.network === X1_MAINNET_NETWORK)
+        return "X1";
+    if (method.network.startsWith("solana:"))
+        return "SOL";
+    if (method.network.startsWith("eip155:"))
+        return "ETH";
+    return null;
+}
+/**
+ * Resolve a v2 manifest's payTo per payment method from the CHAIN — never from
+ * the manifest. `records` are the payTo name's decoded address records,
+ * `authority` its current authority (owner / pNFT holder), exactly the inputs
+ * of {@link paymentAddressFor} (W16, the program's `name_pays_to`).
+ *
+ * The owner fallback is only meaningful on SVM chains (X1 / SOL — the
+ * authority is an SVM key); on ETH only a live VERIFIED record pays, else the
+ * method has no address (`no-verified-record`), never the owner's SVM key.
+ */
+export function resolveManifestPayTo(manifest, input) {
+    const methods = manifest.payment?.methods ?? [];
+    return methods.map((method) => {
+        const chain = paymentMethodChain(method);
+        if (chain === null)
+            return { method, chain, payTo: null, reason: "unsupported-network" };
+        const svm = chain === "X1" || chain === "SOL";
+        const payTo = paymentAddressFor(input.records, svm ? input.authority : null, chain);
+        if (payTo)
+            return { method, chain, payTo };
+        return { method, chain, payTo: null, reason: svm ? "no-authority" : "no-verified-record" };
+    });
+}
+/** Flag every `payment.addresses[]` mirror entry (v1 or v2) whose chain has a
+ *  W16-resolved address that differs. `resolved` maps chain → the address
+ *  {@link paymentAddressFor} returned for the name. */
+export function payToWarnings(manifest, resolved) {
+    const out = [];
+    for (const a of manifest.payment?.addresses ?? []) {
+        const chain = Object.keys(CHAIN_COIN_TYPE).find((c) => CHAIN_COIN_TYPE[c] === a.coinType);
+        const r = chain ? resolved[chain] : undefined;
+        if (r !== undefined && r !== a.address)
+            out.push({ code: "payto-diverges", coinType: a.coinType, claimed: a.address, resolved: r });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // Reading agent text records off a handle's already-fetched records
 // ---------------------------------------------------------------------------
 /** Pick the agent-related well-known keys out of a handle's live text
@@ -193,7 +538,10 @@ export function x402AcceptsFromManifest(manifest, opts) {
     // matching id — "testnet" → X1_TESTNET_NETWORK, anything else (mainnet, the
     // production default) → X1_MAINNET_NETWORK.
     const network = x402?.network ?? (manifest.x1id.network === "testnet" ? X1_TESTNET_NETWORK : X1_MAINNET_NETWORK);
-    const payTo = opts?.payTo ?? manifest.payment?.addresses?.[0]?.address;
+    // v2 NEVER takes a payTo from the manifest: it names an @name and the
+    // caller resolves the address from the chain (resolveManifestPayTo). Only
+    // the legacy v1 shape falls back to its self-reported address mirror.
+    const payTo = opts?.payTo ?? (manifest.x1id.version === 2 ? undefined : manifest.payment?.addresses?.[0]?.address);
     return x402Endpoints.map((e) => {
         const hint = {
             scheme: x402?.scheme ?? "exact",

package/dist/agentPolicy.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Agent spend policies enforced by the registry (program upgrade 6,
+ * OpenProject #8456; spec docs/specs/agent-spend-policy.md).
+ *
+ * The current authority of an `@name` (untokenized owner, or the pNFT holder)
+ * authorises an agent wallet under a policy bound to the name:
+ * `["agent_policy", handle, agent]` holds per-mint caps per rolling period
+ * (native XNT = {@link AGENT_POLICY_NATIVE_MINT}), an expiry and an optional
+ * recipient allow-list. Native XNT is spent from the policy PDA's float (its
+ * lamports above rent); SPL / Token-2022 from a grantor token account through
+ * the policy's OWN delegate `["agent_delegate", policy, createdSlot]`, which
+ * the grantor approves with a plain SPL `Approve`
+ * ({@link buildApproveAgentDelegateIx}). One delegate per policy (Sentinel
+ * run-012 A-04): an allowance approved for one agent's policy can never be
+ * spent by another agent. One delegate per CREATION (D-02): the policy's
+ * `createdSlot` is a seed, so an approval left behind by a revoked policy
+ * can never re-arm when the same `(handle, agent)` policy is created again. A token account has
+ * one delegate, so give each agent (policy) its own token account per mint.
+ *
+ * Kill switches: lock the name (`lock_handle`, lock.ts) — every spend fails
+ * at once; {@link buildRevokeAgentPolicyIx} (works during lockdown and while
+ * locked); {@link buildWithdrawAgentFloatIx}; SPL `Revoke`.
+ *
+ * Tokenized names: pass `holderTokenAccount` (the grantor's canonical pNFT ATA)
+ * to create / update / spend; it is the program's `remaining_accounts[0]`
+ * authority proof.
+ *
+ * Hand-rolled like the rest of this package: no Anchor client, no web3.js.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { PdaFinder } from "./namespacePricing.js";
+export declare const AGENT_POLICY_SEED = "agent_policy";
+export declare const AGENT_DELEGATE_SEED = "agent_delegate";
+/** The "mint" a native-XNT cap is written under (all-zero pubkey). */
+export declare const AGENT_POLICY_NATIVE_MINT = "11111111111111111111111111111111";
+export declare const AGENT_MAX_CAPS = 4;
+export declare const AGENT_MAX_RECIPIENTS = 4;
+export declare const AGENT_PERIOD_MIN_SECS = 60;
+export declare const AGENT_PERIOD_MAX_SECS: number;
+/** `8 + AgentPolicy::INIT_SPACE` (layout v2: `created_slot` appended). */
+export declare const AGENT_POLICY_ACCOUNT_LEN = 525;
+/** `AGENT_POLICY_VERSION` of the accounts this decoder reads. */
+export declare const AGENT_POLICY_LAYOUT_VERSION = 2;
+/** `sha256("global:<name>")[0..8]`, pinned + re-derived in the tests. */
+export declare const CREATE_AGENT_POLICY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const UPDATE_AGENT_POLICY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const FUND_AGENT_POLICY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const WITHDRAW_AGENT_FLOAT_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const REVOKE_AGENT_POLICY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const AGENT_SPEND_NATIVE_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export declare const AGENT_SPEND_SPL_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+/** `sha256("account:AgentPolicy")[0..8]`. */
+export declare const AGENT_POLICY_ACCOUNT_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+/** Program error codes (AgentPolicyError, offset 6190). */
+export declare const AGENT_POLICY_ERRORS: Readonly<Record<number, string>>;
+/** `["agent_policy", handle, agent]`. */
+export declare function deriveAgentPolicyPda(find: PdaFinder, programId: AddressLike, handle: AddressLike, agent: AddressLike): Promise<string>;
+/**
+ * `["agent_delegate", policy, createdSlot (u64 LE)]` — the policy's own SPL
+ * delegate, which the grantor approves on the token account that policy's
+ * agent spends from. `createdSlot` is the policy's generation: read it from
+ * the account ({@link decodeAgentPolicy}`(…).createdSlot`) after
+ * `create_agent_policy` lands. A re-created policy (same address) has a new
+ * `createdSlot`, hence a new delegate (Sentinel run-012 D-02). Since 0.41.0;
+ * 0.40 used `["agent_delegate", policy]`, 0.38–0.39 the grantor (neither on
+ * mainnet).
+ */
+export declare function deriveAgentDelegatePda(find: PdaFinder, programId: AddressLike, agentPolicy: AddressLike, createdSlot: bigint): Promise<string>;
+export interface AgentCap {
+    /** SPL / Token-2022 mint, or {@link AGENT_POLICY_NATIVE_MINT} for native XNT. */
+    readonly mint: AddressLike;
+    /** Max base units per period (> 0). */
+    readonly cap: bigint;
+}
+export interface AgentPolicyTerms {
+    /** Unix seconds; must be in the future. */
+    readonly expiresAt: bigint;
+    readonly periodSecs: bigint;
+    /** 1..=4 caps, unique mints. */
+    readonly caps: readonly AgentCap[];
+    /** 0..=4 recipients; empty = any recipient. */
+    readonly recipients?: readonly AddressLike[];
+}
+/** Client-side mirror of the program's `validate_terms` (null = valid). */
+export declare function agentPolicyTermsProblem(t: AgentPolicyTerms, nowSecs: bigint): string | null;
+/** Borsh `AgentPolicyTerms { expires_at, period_secs, caps: Vec<{mint,cap}>, recipients: Vec<Pubkey> }`. */
+export declare function encodeAgentPolicyTerms(t: AgentPolicyTerms): Uint8Array;
+interface Common {
+    readonly programId: AddressLike;
+}
+interface WithProof {
+    /** Tokenized name: the grantor's canonical pNFT ATA (authority proof). */
+    readonly holderTokenAccount?: AddressLike;
+}
+export interface CreateAgentPolicyParams extends Common, WithProof {
+    readonly grantor: AddressLike;
+    readonly handle: AddressLike;
+    readonly config: AddressLike;
+    /** {@link deriveAgentPolicyPda}(handle, agent). */
+    readonly agentPolicy: AddressLike;
+    readonly agent: AddressLike;
+    readonly terms: AgentPolicyTerms;
+    /** For the client-side check; defaults to the local clock. */
+    readonly nowSecs?: bigint;
+}
+/** `create_agent_policy(agent, terms)`: grantor(s,w), handle, config, agent_policy(w), system [+ holder ATA]. */
+export declare function buildCreateAgentPolicyIx(p: CreateAgentPolicyParams): BuiltInstruction;
+export interface UpdateAgentPolicyParams extends Common, WithProof {
+    readonly grantor: AddressLike;
+    readonly handle: AddressLike;
+    readonly config: AddressLike;
+    readonly agentPolicy: AddressLike;
+    readonly terms: AgentPolicyTerms;
+    readonly nowSecs?: bigint;
+}
+/** `update_agent_policy(terms)`: grantor(s), handle, config, agent_policy(w) [+ holder ATA]. */
+export declare function buildUpdateAgentPolicyIx(p: UpdateAgentPolicyParams): BuiltInstruction;
+export interface FundAgentPolicyParams extends Common {
+    readonly grantor: AddressLike;
+    readonly config: AddressLike;
+    readonly agentPolicy: AddressLike;
+    readonly lamports: bigint;
+}
+/** `fund_agent_policy(amount)`: grantor(s,w), config, agent_policy(w), system. */
+export declare function buildFundAgentPolicyIx(p: FundAgentPolicyParams): BuiltInstruction;
+export interface WithdrawAgentFloatParams extends Common {
+    readonly grantor: AddressLike;
+    readonly agentPolicy: AddressLike;
+    readonly lamports: bigint;
+}
+/** `withdraw_agent_float(amount)`: grantor(s,w), agent_policy(w). Always allowed. */
+export declare function buildWithdrawAgentFloatIx(p: WithdrawAgentFloatParams): BuiltInstruction;
+export interface RevokeAgentPolicyParams extends Common, WithProof {
+    /** Grantor, agent, the name's current authority (with `holderTokenAccount`
+     *  if tokenized), or anyone once the policy is expired / stale. */
+    readonly signer: AddressLike;
+    readonly handle: AddressLike;
+    readonly agentPolicy: AddressLike;
+    /** `policy.grantor` — receives every lamport. */
+    readonly grantor: AddressLike;
+}
+/** `revoke_agent_policy()`: signer(s), handle, agent_policy(w), grantor(w) [+ signer's pNFT ATA]. */
+export declare function buildRevokeAgentPolicyIx(p: RevokeAgentPolicyParams): BuiltInstruction;
+export interface AgentSpendNativeParams extends Common, WithProof {
+    readonly agent: AddressLike;
+    readonly agentPolicy: AddressLike;
+    readonly handle: AddressLike;
+    readonly config: AddressLike;
+    readonly recipient: AddressLike;
+    readonly lamports: bigint;
+}
+/** `agent_spend_native(amount)`: agent(s), agent_policy(w), handle, config, recipient(w) [+ grantor's pNFT ATA]. */
+export declare function buildAgentSpendNativeIx(p: AgentSpendNativeParams): BuiltInstruction;
+export interface AgentSpendSplParams extends Common, WithProof {
+    readonly agent: AddressLike;
+    readonly agentPolicy: AddressLike;
+    readonly handle: AddressLike;
+    readonly config: AddressLike;
+    /** {@link deriveAgentDelegatePda}(agentPolicy, createdSlot) — this policy's own delegate. */
+    readonly agentDelegate: AddressLike;
+    readonly mint: AddressLike;
+    /** A grantor-owned token account approved to `agentDelegate`. */
+    readonly source: AddressLike;
+    /** The recipient's token account (its OWNER is checked against the allow-list). */
+    readonly destination: AddressLike;
+    /** SPL Token or Token-2022 (the mint's owner). */
+    readonly tokenProgram: AddressLike;
+    readonly amount: bigint;
+}
+/** `agent_spend_spl(amount)`: agent(s), agent_policy(w), handle, config, agent_delegate, mint, source(w), destination(w), token_program [+ grantor's pNFT ATA]. */
+export declare function buildAgentSpendSplIx(p: AgentSpendSplParams): BuiltInstruction;
+export interface ApproveAgentDelegateParams {
+    readonly tokenProgram: AddressLike;
+    /** The grantor's token account the agent will spend from. */
+    readonly source: AddressLike;
+    /** {@link deriveAgentDelegatePda}(agentPolicy, createdSlot) of the ONE policy (creation) this allowance is for. */
+    readonly agentDelegate: AddressLike;
+    readonly grantor: AddressLike;
+    /** The SPL allowance (the outer bound; the policy cap is the inner one). */
+    readonly amount: bigint;
+}
+/** SPL `Approve` (tag 4) of the agent delegate — signed by the grantor. */
+export declare function buildApproveAgentDelegateIx(p: ApproveAgentDelegateParams): BuiltInstruction;
+/**
+ * SPL `Revoke` (tag 5) — the grantor cuts the policy whose delegate is
+ * approved on that token account off it. `revoke_agent_policy` closes the
+ * policy but cannot clear the SPL approval (only the token-account owner
+ * can). The leftover approval names a delegate no policy can ever sign as
+ * again (re-creating the same `(handle, agent)` policy gets a new
+ * `createdSlot` and a new delegate), so an old approval can never re-arm;
+ * appending this still tidies the token account (it holds one delegate).
+ */
+export declare function buildRevokeAgentDelegateIx(p: {
+    readonly tokenProgram: AddressLike;
+    readonly source: AddressLike;
+    readonly grantor: AddressLike;
+}): BuiltInstruction;
+export interface AgentMintCapState {
+    readonly mint: string;
+    readonly native: boolean;
+    readonly cap: bigint;
+    readonly spent: bigint;
+    readonly periodStart: bigint;
+}
+export interface AgentPolicyAccount {
+    readonly version: number;
+    readonly bump: number;
+    readonly delegateBump: number;
+    readonly handle: string;
+    readonly agent: string;
+    readonly grantor: string;
+    /** `max(registered_at, holder_epoch)` at grant. */
+    readonly epoch: bigint;
+    readonly createdAt: bigint;
+    readonly updatedAt: bigint;
+    readonly expiresAt: bigint;
+    readonly periodSecs: bigint;
+    readonly caps: readonly AgentMintCapState[];
+    /** Empty = any recipient. */
+    readonly recipients: readonly string[];
+    readonly totalSpends: bigint;
+    readonly lastSpentAt: bigint;
+    /** Slot of `create_agent_policy`: the delegate's generation seed. */
+    readonly createdSlot: bigint;
+}
+/** Decode an `AgentPolicy` account (null when not one). */
+export declare function decodeAgentPolicy(data: Uint8Array): AgentPolicyAccount | null;
+/**
+ * What the agent may still spend of `mint` at `nowSecs` (the program's
+ * `roll_period` applied): null when the mint has no cap. Does NOT include
+ * the float / SPL allowance bound, the lock, or the policy's liveness.
+ */
+export declare function agentPolicyRemaining(p: AgentPolicyAccount, mint: AddressLike, nowSecs: bigint): {
+    readonly remaining: bigint;
+    readonly periodEndsAt: bigint;
+    readonly expired: boolean;
+} | null;
+export {};