@floatonnear/float-adapter 0.0.0-stage → 0.1.0

package/dist/handlers.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The /v1 endpoints the existing Float dashboard already calls, served from
+ * NEAR vault views.
+ *
+ * `view` is injected so every handler is testable without a chain — the
+ * mapping and the shape of what the UI receives are exactly where a silent
+ * wrong-but-plausible number would come from.
+ */
+import { type ApiAgent, type Payment, type VaultOutcome } from "./map.js";
+export type ViewFn = <T>(method: string, args?: unknown) => Promise<T>;
+/** What the relayer recorded about a Base delivery. */
+export interface DeliveryRecord {
+    mode: "vault" | "operator";
+    baseTxHash: string;
+    payee: string;
+    amount: string;
+    at: string;
+}
+export interface AdapterConfig {
+    token: string;
+    decimals: number;
+    /**
+     * Base deliveries, keyed by request id, as the relayer recorded them.
+     *
+     * OFF-CHAIN ON PURPOSE. The NEAR budget already moved when the vault signed;
+     * delivery on Base is something an operator observed, not something the
+     * contract can attest. Keeping it in a separate map means a missing or lying
+     * ledger can only ever UNDERSTATE delivery — it can never invent budget or
+     * contradict the chain.
+     */
+    deliveries?: Record<string, DeliveryRecord>;
+    /** Bounded, in-memory. See `recordBlocked`. */
+    blockedRing: Payment[];
+    maxBlocked: number;
+    /**
+     * Refusals recovered FROM CHAIN by scripts/scan-blocked.mjs, keyed by
+     * request id.
+     *
+     * The in-memory ring above only held refusals this process personally
+     * witnessed, so the most important thing the vault does — refusing a payment
+     * because a SHARED pool is empty — vanished on restart and was invisible for
+     * any payment made by another client. A refused request is deliberately not
+     * stored in contract state (that is the storage griefing vector of §2), but
+     * the NEP-297 event survives in the receipt and can be read back. These rows
+     * carry a tx hash and are therefore independently checkable. The ring's are
+     * not.
+     */
+    chainBlocked?: Record<string, ChainBlocked>;
+    /**
+     * The block range the scanner has actually covered. Without it, "no
+     * refusals happened" and "we have not looked there" render identically —
+     * which is the confusion this feature exists to remove.
+     */
+    blockedScan?: {
+        from: number;
+        to: number;
+        /** Spans inside from..to that were never read. Unknown, not empty. */
+        holes?: Array<{
+            from: number;
+            to: number;
+        }>;
+    } | null;
+}
+/** One refusal, as recovered from a receipt outcome. */
+export interface ChainBlocked {
+    requestId: string;
+    nodeId: number;
+    reasonCode: string;
+    agent: string;
+    txHash: string;
+    blockHeight: number;
+    blockTimestampNs: string | number;
+}
+/**
+ * Blocked attempts are NOT stored on-chain — the hot path returns them as a
+ * value and emits an event, deliberately, so an agent cannot grow the vault's
+ * storage bill by spamming rejects.
+ *
+ * So the adapter remembers the ones it SEES, in a bounded in-memory ring. That
+ * covers blocks made through this product, which is what the dashboard is
+ * showing. Blocks made by another client, or before this process started, are
+ * not here and cannot be — the dashboard says so rather than implying none
+ * happened.
+ */
+/**
+ * Chain-recovered refusals as Payment rows.
+ *
+ * Deduped against the in-memory ring by request id, preferring the chain copy
+ * — it is the one that carries a tx hash a reader can check for themselves.
+ */
+export declare function chainBlockedPayments(cfg: AdapterConfig, nodeLabels: Record<number, string>): Payment[];
+export declare function recordBlocked(cfg: AdapterConfig, p: Payment): void;
+/** Where this vault lives, so the UI never has to hardcode a chain. */
+export interface VaultInfo {
+    vaultId: string;
+    tokenId: string;
+    tokenDecimals: number;
+    network: string;
+    /** NEAR Explorer base for the network the vault is actually on. */
+    explorerBase: string;
+    owner: string;
+    paused: boolean;
+    clockMode: string;
+    strictAllocation: boolean;
+    /**
+     * The vault's ACTUAL NEP-141 balance, base units.
+     *
+     * Deliberately separate from `treasury.amount` on /v1/dashboard, which is the
+     * root node's remaining DAILY BUDGET. They are different quantities and the
+     * funding page needs this one: fund 10,000 USDC against a 100/day root cap
+     * and the budget figure still reads 40, which would look like the deposit
+     * never arrived. Null when the token contract cannot be read.
+     */
+    vaultTokenBalance: string | null;
+}
+/**
+ * `near` / `testnet` / anything else. Derived from the network the contract
+ * reports rather than from an env var, so a UI pointed at testnet cannot link
+ * to a mainnet explorer and show "not found".
+ */
+export declare function explorerBaseFor(network: string): string;
+/** A view against an arbitrary contract — the token, not the vault. */
+export type ViewOnFn = (contractId: string, method: string, args?: unknown) => Promise<string | null>;
+export declare function getVaultInfo(view: ViewFn, cfg: AdapterConfig, viewOn: ViewOnFn): Promise<VaultInfo>;
+export interface AgentKeyView {
+    accountId: string;
+    nodeId: number;
+    label: string;
+    frozen: boolean;
+    keys: {
+        publicKey: string;
+        /** True only if the key really is a function-call key. */
+        restricted: boolean;
+        receiverId: string | null;
+        methodNames: string[];
+        allowanceYocto: string | null;
+    }[];
+    /** Set when the key list could not be read, so the UI can say so. */
+    error?: string;
+}
+export type KeyFn = (accountId: string) => Promise<{
+    public_key: string;
+    access_key: {
+        permission: "FullAccess" | {
+            FunctionCall: {
+                allowance: string | null;
+                receiver_id: string;
+                method_names: string[];
+            };
+        };
+    };
+}[]>;
+/**
+ * The bound agent accounts, with their access keys read FROM THE CHAIN.
+ *
+ * The restriction is the product's central security claim, so the page that
+ * states it must not state it from a constant. A hardcoded "restricted to
+ * request_payment" would keep rendering happily if someone added a full-access
+ * key to an agent account — exactly the regression a reader of that page is
+ * trying to rule out. `restricted` here is computed from the permission NEAR
+ * reports, and a FullAccess key makes it false.
+ */
+export declare function getAgentKeys(view: ViewFn, keys: KeyFn, _cfg: AdapterConfig): Promise<AgentKeyView[]>;
+export declare function getDashboard(view: ViewFn, cfg: AdapterConfig): Promise<{
+    owner: {
+        authMethod: string;
+        walletAddress: string;
+        displayName: string;
+    };
+    treasury: {
+        ownerId: string;
+        walletAddress: string;
+        createdAt: string;
+        amount: string;
+        currency: string;
+        decimals: number;
+    };
+    agents: ApiAgent[];
+    blockedCoverage: {
+        from: number;
+        to: number;
+        /** Spans inside from..to that were never read. Unknown, not empty. */
+        holes?: Array<{
+            from: number;
+            to: number;
+        }>;
+    } | null | undefined;
+    transactionStats: {
+        total: number;
+        approved: number;
+        blocked: number;
+        failed: number;
+        other: number;
+    };
+    recentActivity: {
+        id: string;
+        agent: string;
+        venue: string;
+        amount: string;
+        rail: string;
+        time: string;
+        status: string;
+    }[];
+    paused: boolean;
+}>;
+export declare function getSpendHistory(view: ViewFn, cfg: AdapterConfig, limit: number, offset: number): Promise<{
+    payments: Payment[];
+}>;
+/** Called by the pay endpoint so a block the product caused shows up as a row. */
+export declare function paymentFromOutcome(cfg: AdapterConfig, outcome: VaultOutcome, labels: Record<number, string>, amountHuman: string, recipient: string): Payment | null;

package/dist/handlers.js

@@ -0,0 +1,246 @@
+/**
+ * The /v1 endpoints the existing Float dashboard already calls, served from
+ * NEAR vault views.
+ *
+ * `view` is injected so every handler is testable without a chain — the
+ * mapping and the shape of what the UI receives are exactly where a silent
+ * wrong-but-plausible number would come from.
+ */
+import { blockedToPayment, lifetimeByNode, requestToPayment, REASONS, treeToApiAgents, } from "./map.js";
+/**
+ * Blocked attempts are NOT stored on-chain — the hot path returns them as a
+ * value and emits an event, deliberately, so an agent cannot grow the vault's
+ * storage bill by spamming rejects.
+ *
+ * So the adapter remembers the ones it SEES, in a bounded in-memory ring. That
+ * covers blocks made through this product, which is what the dashboard is
+ * showing. Blocks made by another client, or before this process started, are
+ * not here and cannot be — the dashboard says so rather than implying none
+ * happened.
+ */
+/**
+ * Chain-recovered refusals as Payment rows.
+ *
+ * Deduped against the in-memory ring by request id, preferring the chain copy
+ * — it is the one that carries a tx hash a reader can check for themselves.
+ */
+export function chainBlockedPayments(cfg, nodeLabels) {
+    const seen = new Set(cfg.blockedRing.map((p) => p.id));
+    return Object.values(cfg.chainBlocked ?? {})
+        .filter((b) => !seen.has(b.requestId))
+        .map((b) => ({
+        id: b.requestId,
+        agentId: String(b.nodeId),
+        agentName: nodeLabels[b.nodeId] ?? `node-${b.nodeId}`,
+        // The amount is NOT in the event, and inventing one would be worse than
+        // showing none: a refused payment moved nothing, and a plausible figure
+        // would read as fact.
+        amount: "0",
+        currency: "USDC",
+        recipientAddress: "",
+        venue: "",
+        rail: "policy",
+        status: "blocked",
+        txSignature: b.txHash,
+        createdAt: new Date(Number(BigInt(b.blockTimestampNs) / 1000000n)).toISOString(),
+        blockReason: b.reasonCode,
+        blockMessage: REASONS[b.reasonCode] ?? b.reasonCode,
+        prompt: null,
+        resultUrl: null,
+    }));
+}
+export function recordBlocked(cfg, p) {
+    cfg.blockedRing.unshift(p);
+    if (cfg.blockedRing.length > cfg.maxBlocked)
+        cfg.blockedRing.length = cfg.maxBlocked;
+}
+async function loadTreeAndUsage(view, cfg) {
+    const tree = await view("get_tree", {});
+    const budgets = new Map();
+    const labels = {};
+    // CONCURRENT, not sequential. One view per node is bounded by MAX_NODES (64),
+    // but issuing them in series costs a full testnet round-trip EACH: measured
+    // at 30s for a five-node tree, which is not a dashboard, it is a progress
+    // bar. Only `get_tree` is a real dependency; the per-node budgets depend on
+    // nothing but it. Pinned by the concurrency test in handlers.test.ts.
+    for (const n of tree)
+        labels[n.id] = n.label;
+    const fetched = await Promise.all(tree.map((n) => view("get_node_budget", {
+        node_id: n.id,
+        token: cfg.token,
+        day: null,
+    })));
+    tree.forEach((n, i) => {
+        const b = fetched[i];
+        budgets.set(n.id, b ? { executed: b.executed, pending: b.pending } : { executed: "0", pending: "0" });
+    });
+    return { tree, budgets, labels };
+}
+/**
+ * `near` / `testnet` / anything else. Derived from the network the contract
+ * reports rather than from an env var, so a UI pointed at testnet cannot link
+ * to a mainnet explorer and show "not found".
+ */
+export function explorerBaseFor(network) {
+    return network === "mainnet" || network === "near"
+        ? "https://nearblocks.io"
+        : "https://testnet.nearblocks.io";
+}
+export async function getVaultInfo(view, cfg, viewOn) {
+    // `get_base_config` used to be read here alongside `get_config`. The
+    // MPC/Base rail and its config were removed from the contract on
+    // 2026-10-28, so there is no method left to call and no rail to report.
+    const c = await view("get_config", {});
+    // Read off the TOKEN contract, not the vault — so it is the real balance and
+    // not an echo of the vault's own bookkeeping. Null rather than "0" on
+    // failure: zero would read as "the deposit is not here", which is a
+    // different claim from "we could not look".
+    const vaultTokenBalance = await viewOn(cfg.token, "ft_balance_of", {
+        account_id: c.vault_id,
+    }).catch(() => null);
+    return {
+        vaultId: c.vault_id,
+        tokenId: cfg.token,
+        tokenDecimals: cfg.decimals,
+        network: c.network,
+        explorerBase: explorerBaseFor(c.network),
+        owner: c.owner,
+        paused: c.paused,
+        clockMode: c.clock_mode,
+        strictAllocation: c.strict_allocation,
+        vaultTokenBalance,
+    };
+}
+/**
+ * The bound agent accounts, with their access keys read FROM THE CHAIN.
+ *
+ * The restriction is the product's central security claim, so the page that
+ * states it must not state it from a constant. A hardcoded "restricted to
+ * request_payment" would keep rendering happily if someone added a full-access
+ * key to an agent account — exactly the regression a reader of that page is
+ * trying to rule out. `restricted` here is computed from the permission NEAR
+ * reports, and a FullAccess key makes it false.
+ */
+export async function getAgentKeys(view, keys, _cfg) {
+    const tree = await view("get_tree", {});
+    const bound = tree.filter((n) => n.account);
+    return Promise.all(bound.map(async (n) => {
+        const base = {
+            accountId: n.account,
+            nodeId: n.id,
+            label: n.label,
+            frozen: n.frozen,
+        };
+        try {
+            const list = await keys(n.account);
+            return {
+                ...base,
+                keys: list.map((k) => {
+                    const p = k.access_key.permission;
+                    const fc = typeof p === "object" && "FunctionCall" in p ? p.FunctionCall : null;
+                    return {
+                        publicKey: k.public_key,
+                        restricted: fc !== null,
+                        receiverId: fc?.receiver_id ?? null,
+                        methodNames: fc?.method_names ?? [],
+                        allowanceYocto: fc?.allowance ?? null,
+                    };
+                }),
+            };
+        }
+        catch (e) {
+            // An unreadable key list is reported, never silently rendered as "no
+            // keys" — that would read as "nothing is authorised here", the
+            // opposite of unknown.
+            return { ...base, keys: [], error: e instanceof Error ? e.message : String(e) };
+        }
+    }));
+}
+export async function getDashboard(view, cfg) {
+    const { tree, budgets, labels } = await loadTreeAndUsage(view, cfg);
+    // Also concurrent: neither depends on the other.
+    const [requests, cfgView] = await Promise.all([
+        view("list_requests", { from_index: 0, limit: 20 }),
+        view("get_config", {}),
+    ]);
+    const agents = treeToApiAgents(tree, budgets, cfg.decimals, lifetimeByNode(requests));
+    const onchain = requests.map((r) => requestToPayment(r, labels, cfg.decimals, cfg.deliveries?.[r.request_id]));
+    const recent = [...chainBlockedPayments(cfg, labels), ...cfg.blockedRing, ...onchain]
+        .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
+        .slice(0, 20);
+    const root = tree.find((n) => n.parent === null);
+    const rootUsage = root ? budgets.get(root.id) : undefined;
+    return {
+        owner: { authMethod: "wallet", walletAddress: cfgView.owner, displayName: cfgView.owner },
+        treasury: {
+            ownerId: cfgView.owner,
+            walletAddress: cfgView.vault_id,
+            createdAt: new Date(0).toISOString(),
+            // The vault holds the tokens; the figure the dashboard cares about is
+            // how much of the ROOT budget is still available today.
+            amount: root?.limits[0]
+                ? (BigInt(root.limits[0].daily_cap) -
+                    BigInt(rootUsage?.executed ?? "0") -
+                    BigInt(rootUsage?.pending ?? "0")).toString()
+                : "0",
+            currency: "USDC",
+            decimals: cfg.decimals,
+        },
+        agents,
+        // What the refusal history actually covers. A UI that shows "0 blocked"
+        // without this cannot distinguish an honest zero from an unscanned range.
+        blockedCoverage: cfg.blockedScan,
+        transactionStats: {
+            total: onchain.length + cfg.blockedRing.length + Object.keys(cfg.chainBlocked ?? {}).length,
+            // The Base rail's terminal states count as approved. "success" alone was
+            // written when NEAR was the only rail; once Base payments report
+            // "signed"/"delivered" it rendered "4 transactions, 0 approved /
+            // 0 blocked" — every payment the vault had authorized vanished from the
+            // count. The UI's own list and this total disagreed on screen.
+            approved: onchain.filter((p) => ["success", "signed", "delivered"].includes(p.status)).length,
+            blocked: cfg.blockedRing.length + Object.keys(cfg.chainBlocked ?? {}).length,
+            failed: onchain.filter((p) => p.status === "failed").length,
+            other: onchain.filter((p) => p.status === "pending").length,
+        },
+        recentActivity: recent.map((p) => ({
+            id: p.id,
+            agent: p.agentName,
+            venue: p.venue,
+            amount: p.amount,
+            rail: p.rail,
+            time: p.createdAt,
+            status: p.status,
+        })),
+        paused: cfgView.paused,
+    };
+}
+export async function getSpendHistory(view, cfg, limit, offset) {
+    const tree = await view("get_tree", {});
+    const labels = {};
+    for (const n of tree)
+        labels[n.id] = n.label;
+    const requests = await view("list_requests", {
+        from_index: offset,
+        limit,
+    });
+    const onchain = requests.map((r) => requestToPayment(r, labels, cfg.decimals, cfg.deliveries?.[r.request_id]));
+    // Blocked rows only belong on the FIRST page: they are not part of the
+    // contract's paged list, so splicing them into later pages would duplicate
+    // them as the UI scrolls.
+    //
+    // Sorted by time rather than concatenated, because chain-recovered refusals
+    // can be older than the in-memory ones and a bare prepend would show them
+    // above newer activity.
+    const merged = offset === 0
+        ? [...chainBlockedPayments(cfg, labels), ...cfg.blockedRing, ...onchain].sort((a, b) => a.createdAt < b.createdAt ? 1 : -1)
+        : onchain;
+    return { payments: merged.slice(0, limit) };
+}
+/** Called by the pay endpoint so a block the product caused shows up as a row. */
+export function paymentFromOutcome(cfg, outcome, labels, amountHuman, recipient) {
+    if (outcome.status !== "BLOCKED")
+        return null;
+    const p = blockedToPayment(outcome, labels, amountHuman, recipient, new Date().toISOString());
+    recordBlocked(cfg, p);
+    return p;
+}

package/dist/keyring.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Which agent signs a payment.
+ *
+ * The adapter used to hold exactly one agent credential, in
+ * NEAR_VAULT_AGENT_ID / NEAR_VAULT_AGENT_KEY, and `POST /v1/pay` always signed
+ * as that agent. The dashboard meanwhile renders the whole tree. So a vault
+ * with sixteen agents showed sixteen rows and could act as one of them — and
+ * the sixteen-agent demo had to bypass the product entirely and drive the CLI
+ * instead.
+ *
+ * This matters more than it looks, because the contract resolves the spending
+ * node from the SIGNER (`account_to_node`), not from anything in the request
+ * body. Which key signs *is* which budget is charged. A single-key adapter
+ * cannot exercise a hierarchy at all; it can only ever spend one leaf.
+ *
+ * On holding several keys at once: each is the restricted key from
+ * `create_agent_account`, which can call only `request_payment` on its own
+ * vault, cannot call other contracts, and cannot attach a deposit. The vault
+ * enforces every cap regardless of who holds the key, so the blast radius of
+ * the whole keyring is bounded by the tree's own limits. That is the same
+ * bound as for one key, applied more times.
+ */
+export interface AgentCredential {
+    agentId: string;
+    secret: string;
+    /** Present when known; lets a caller select by node instead of account id. */
+    nodeId?: number;
+}
+export interface Keyring {
+    /** agent account id -> credential */
+    byAccount: Map<string, AgentCredential>;
+    /** node id -> credential */
+    byNode: Map<number, AgentCredential>;
+    /**
+     * Used when a request names no agent. Preserves the previous single-agent
+     * behaviour exactly, so existing deployments and the dashboard's own calls
+     * keep working untouched.
+     */
+    fallback?: AgentCredential;
+}
+export declare function emptyKeyring(): Keyring;
+/**
+ * Build a keyring from the singular env vars plus, optionally, the JSON file
+ * `create-float` writes at `.float/agent-keys.json`:
+ *
+ *   [{ "nodeId": 3, "agentId": "r1.float.me.testnet", "secret": "ed25519:..." }]
+ *
+ * The singular env pair stays authoritative for the fallback, so adding a file
+ * can never silently change which agent an un-targeted payment comes from.
+ */
+export declare function loadKeyring(env: {
+    agentId?: string;
+    agentKey?: string;
+    agentKeysPath?: string;
+}): Keyring;
+export declare class AgentSelectionError extends Error {
+}
+/**
+ * Pick the credential for a payment request.
+ *
+ * Errors name every agent that IS available. A selection failure is almost
+ * always a typo or a stale node id, and an error that says only "not found"
+ * costs the caller another round trip to discover what the valid options were.
+ */
+export declare function selectAgent(ring: Keyring, want?: {
+    agent?: string;
+    nodeId?: number;
+}): AgentCredential;

package/dist/keyring.js

@@ -0,0 +1,121 @@
+/**
+ * Which agent signs a payment.
+ *
+ * The adapter used to hold exactly one agent credential, in
+ * NEAR_VAULT_AGENT_ID / NEAR_VAULT_AGENT_KEY, and `POST /v1/pay` always signed
+ * as that agent. The dashboard meanwhile renders the whole tree. So a vault
+ * with sixteen agents showed sixteen rows and could act as one of them — and
+ * the sixteen-agent demo had to bypass the product entirely and drive the CLI
+ * instead.
+ *
+ * This matters more than it looks, because the contract resolves the spending
+ * node from the SIGNER (`account_to_node`), not from anything in the request
+ * body. Which key signs *is* which budget is charged. A single-key adapter
+ * cannot exercise a hierarchy at all; it can only ever spend one leaf.
+ *
+ * On holding several keys at once: each is the restricted key from
+ * `create_agent_account`, which can call only `request_payment` on its own
+ * vault, cannot call other contracts, and cannot attach a deposit. The vault
+ * enforces every cap regardless of who holds the key, so the blast radius of
+ * the whole keyring is bounded by the tree's own limits. That is the same
+ * bound as for one key, applied more times.
+ */
+import { readFileSync, existsSync } from "node:fs";
+export function emptyKeyring() {
+    return { byAccount: new Map(), byNode: new Map() };
+}
+/**
+ * Build a keyring from the singular env vars plus, optionally, the JSON file
+ * `create-float` writes at `.float/agent-keys.json`:
+ *
+ *   [{ "nodeId": 3, "agentId": "r1.float.me.testnet", "secret": "ed25519:..." }]
+ *
+ * The singular env pair stays authoritative for the fallback, so adding a file
+ * can never silently change which agent an un-targeted payment comes from.
+ */
+export function loadKeyring(env) {
+    const ring = emptyKeyring();
+    const add = (c) => {
+        ring.byAccount.set(c.agentId, c);
+        if (typeof c.nodeId === "number")
+            ring.byNode.set(c.nodeId, c);
+    };
+    if (env.agentKeysPath && existsSync(env.agentKeysPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(env.agentKeysPath, "utf8"));
+        }
+        catch {
+            // A malformed keyring must not take the server down, and must not be
+            // mistaken for an empty one. Paying with an unknown agent will fail
+            // loudly at selection time with a message that lists what IS loaded.
+            parsed = null;
+        }
+        if (Array.isArray(parsed)) {
+            for (const e of parsed) {
+                if (e && typeof e.agentId === "string" && typeof e.secret === "string") {
+                    add({
+                        agentId: e.agentId,
+                        secret: e.secret,
+                        nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+                    });
+                }
+            }
+        }
+    }
+    if (env.agentId && env.agentKey) {
+        const c = { agentId: env.agentId, secret: env.agentKey };
+        add(c);
+        ring.fallback = c;
+    }
+    else if (ring.byAccount.size === 1) {
+        // Exactly one key in the file and no env pair: unambiguous, so use it.
+        // More than one with no env pair is deliberately NOT guessed at — see
+        // selectAgent.
+        ring.fallback = [...ring.byAccount.values()][0];
+    }
+    return ring;
+}
+export class AgentSelectionError extends Error {
+}
+/**
+ * Pick the credential for a payment request.
+ *
+ * Errors name every agent that IS available. A selection failure is almost
+ * always a typo or a stale node id, and an error that says only "not found"
+ * costs the caller another round trip to discover what the valid options were.
+ */
+export function selectAgent(ring, want = {}) {
+    const known = () => {
+        const list = [...ring.byAccount.values()].map((c) => `${c.agentId}${typeof c.nodeId === "number" ? ` (node ${c.nodeId})` : ""}`);
+        return list.length ? list.join(", ") : "none";
+    };
+    if (want.agent !== undefined) {
+        const c = ring.byAccount.get(want.agent);
+        if (!c) {
+            throw new AgentSelectionError(`no key for agent '${want.agent}'. Loaded agents: ${known()}.`);
+        }
+        return c;
+    }
+    if (want.nodeId !== undefined) {
+        const c = ring.byNode.get(want.nodeId);
+        if (!c) {
+            throw new AgentSelectionError(`no key bound to node ${want.nodeId}. Loaded agents: ${known()}. ` +
+                `Node ids come from the keyring file; a key added via ` +
+                `NEAR_VAULT_AGENT_ID alone has no node id attached.`);
+        }
+        return c;
+    }
+    if (ring.fallback)
+        return ring.fallback;
+    if (ring.byAccount.size > 1) {
+        // Refuse rather than guess. Picking arbitrarily would charge a budget the
+        // caller did not choose, and the payment would succeed — so the mistake
+        // would surface later as a confusing balance, not as an error.
+        throw new AgentSelectionError(`several agents are loaded and the request named none, so there is no ` +
+            `safe default. Pass "agent" or "nodeId". Loaded agents: ${known()}.`);
+    }
+    throw new AgentSelectionError("no agent credentials are configured. Set NEAR_VAULT_AGENT_ID and " +
+        "NEAR_VAULT_AGENT_KEY, or point NEAR_VAULT_AGENT_KEYS at the " +
+        "agent-keys.json written by create-float.");
+}