@mysten-incubation/sui-agent-pass 0.0.0 → 0.1.0

package/dist/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from 'node:child_process';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { select } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { clientFor, readStatus } from './chain.js';
+import { cliInvocation, defaultRoot, forgetSession, openBrowser, servePlugin, servePluginHttp, } from './plugin.js';
+import { startServer } from './server.js';
+import { SessionStore } from './storage.js';
+const quote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+/**
+ * Picks several things one at a time with arrows and enter, the way a single-choice menu
+ * works, instead of a checkbox whose space key many people never find. Each pick leaves the
+ * list; the last entry ends the picking. `atLeastOne` refuses to end with nothing picked.
+ */
+async function pickMany(message, choices, done, atLeastOne) {
+    const picked = [];
+    let left = [...choices];
+    while (left.length) {
+        const pick = await select({
+            message: picked.length ? `${message} (${picked.length} picked so far)` : message,
+            choices: [...left, { name: done, value: null }],
+        });
+        if (pick === null) {
+            if (picked.length || !atLeastOne)
+                break;
+            console.log('Pick at least one.');
+            continue;
+        }
+        picked.push(pick);
+        left = left.filter((c) => c.value !== pick);
+    }
+    return picked;
+}
+export async function serve(store, port = 0, open = true) {
+    const server = await startServer(store, port);
+    console.log(`\nOwner page: ${server.ownerUrl}\nSession address: ${store.state.sessionAddress}\nSession directory: ${store.directory}`);
+    console.log(`\nAfter authorization, register the signer with your agent (from the agent's working directory for Claude Code):\n${cliInvocation().map(quote).join(' ')} connect --session ${quote(store.directory)} --client claude-code\nOther clients: --client claude-desktop | cursor | hermes | codex | json\n\nKeep this process running. Ctrl-C stops signing; use the owner page to revoke on chain.`);
+    if (open)
+        openBrowser(server.ownerUrl);
+    const stop = () => {
+        void server.close().then(() => process.exit(0));
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return server;
+}
+const NETWORKS = ['localnet', 'testnet', 'devnet', 'mainnet'];
+/** Load the deployment from an explicit path, or the bundled deployment committed for a network. */
+const program = new Command().name('agent-pass').description('A pass for autonomous agents');
+program
+    .command('serve')
+    .description("Advanced: run one session's HTTP signer in the foreground, for agents that cannot start a process themselves. The stdio server registered by connect starts on demand and needs no serve.")
+    .requiredOption('--session <directory>')
+    .option('--port <port>', 'Local port', '0')
+    .option('--no-open')
+    .action(async (o) => {
+    await serve(await SessionStore.open(resolve(o.session)), Number(o.port), o.open);
+});
+program
+    .command('status')
+    .requiredOption('--session <directory>')
+    .action(async (o) => {
+    const { state } = await SessionStore.open(resolve(o.session));
+    if (!state.active)
+        return console.log('Awaiting owner authorization. Run serve to reopen the review page.');
+    console.log(JSON.stringify(await readStatus(clientFor(state.deployment), state.deployment, state.active, state.sessionAddress), null, 2));
+});
+program
+    .command('forget')
+    .description("Retire a session whose pass is over: refuses while the pass is live, returns the key's gas float to the owner, then deletes the directory and its key")
+    .requiredOption('--session <directory>')
+    .action(async (o) => {
+    const { swept } = await forgetSession(resolve(o.session));
+    console.log(swept
+        ? `Returned ${swept.amount} MIST of gas to the owner (${swept.digest}); session deleted.`
+        : 'Nothing left to return; session deleted.');
+});
+program
+    .command('mcp')
+    .description('Stdio MCP for the Claude Code plugin: propose, watch, sign for and revoke passes')
+    .option('--root <directory>', 'Sessions and default deployment', defaultRoot())
+    .option('--deployment <path>', 'deployment.json used for new passes')
+    .option('--no-open', 'Do not open the browser for owner pages')
+    .option('--http <port>', 'Serve on a local HTTP endpoint instead of stdio; writes url and bearer token to <root>/mcp-http.json')
+    .action(async (o) => {
+    const options = {
+        root: resolve(o.root),
+        deployment: o.deployment,
+        openBrowser: o.open,
+    };
+    if (o.http === undefined)
+        return servePlugin(options);
+    const { url } = await servePluginHttp(options, Number(o.http));
+    console.error(`agent-pass MCP at ${url}; bearer token in ${join(options.root, 'mcp-http.json')}`);
+});
+const CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'hermes', 'codex', 'json'];
+/** Merges one server entry into a JSON MCP config file, creating it if needed. */
+async function mergeJsonConfig(path, entry) {
+    const current = await readFile(path, 'utf8')
+        .then((t) => JSON.parse(t))
+        .catch(() => ({}));
+    current.mcpServers = { ...(current.mcpServers ?? {}), 'agent-pass': entry };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(current, null, 2) + '\n', { mode: 0o600 });
+    console.log(`Wrote agent-pass into ${path}. Restart the client to load it.`);
+}
+async function claudeMcpAdd(args) {
+    const child = spawn('claude', ['mcp', 'add', ...args], { stdio: 'inherit' });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`claude mcp add exited ${code}`)));
+    });
+}
+/** Writes the signer into one client's MCP configuration; the stdio form needs no running process. */
+async function registerClient(client, http) {
+    const [command, ...args] = cliInvocation();
+    const stdio = { command, args: [...args, 'mcp'] };
+    const home = homedir();
+    switch (client) {
+        case 'claude-code':
+            if (http)
+                await claudeMcpAdd([
+                    '--transport',
+                    'http',
+                    '--scope',
+                    'local',
+                    'agent-pass',
+                    http.url,
+                    '--header',
+                    http.headers.Authorization,
+                ]);
+            else
+                await claudeMcpAdd([
+                    '--transport',
+                    'stdio',
+                    '--scope',
+                    'user',
+                    'agent-pass',
+                    '--',
+                    stdio.command,
+                    ...stdio.args,
+                ]);
+            return;
+        case 'claude-desktop': {
+            if (http)
+                throw new Error('Claude Desktop starts MCP servers itself; run connect without --session to register the stdio server');
+            const path = process.platform === 'darwin'
+                ? join(home, 'Library/Application Support/Claude/claude_desktop_config.json')
+                : process.platform === 'win32'
+                    ? join(process.env.APPDATA ?? join(home, 'AppData/Roaming'), 'Claude/claude_desktop_config.json')
+                    : join(home, '.config/Claude/claude_desktop_config.json');
+            return mergeJsonConfig(path, stdio);
+        }
+        case 'cursor':
+            return mergeJsonConfig(join(home, '.cursor/mcp.json'), http ?? stdio);
+        case 'hermes':
+            console.log(`Add to ~/.hermes/config.yaml under mcp_servers:\n\n  agent-pass:\n${http
+                ? `    url: "${http.url}"\n    headers:\n      Authorization: "${http.headers.Authorization}"`
+                : `    command: "${stdio.command}"\n    args: ${JSON.stringify(stdio.args)}`}\n\nThen restart Hermes; the tools appear in "hermes tools list".`);
+            return;
+        case 'codex':
+            console.log(`Add to ~/.codex/config.toml:\n\n[mcp_servers.agent-pass]\n${http
+                ? `url = "${http.url}"\nhttp_headers = { Authorization = "${http.headers.Authorization}" }`
+                : `command = "${stdio.command}"\nargs = ${JSON.stringify(stdio.args)}`}\n`);
+            return;
+        case 'json':
+            console.log(JSON.stringify({ mcpServers: { 'agent-pass': http ?? stdio } }, null, 2));
+    }
+}
+/** The agents on this machine, as far as their usual files show; nothing is preselected. */
+async function chooseClients() {
+    const home = homedir();
+    const found = async (path) => access(path).then(() => ' (found)', () => '');
+    const onPath = (bin) => new Promise((done) => {
+        const child = spawn('sh', ['-c', `command -v ${bin}`], { stdio: 'ignore' });
+        child.once('error', () => done(''));
+        child.once('exit', (code) => done(code === 0 ? ' (found)' : ''));
+    });
+    const desktopConfig = process.platform === 'darwin'
+        ? join(home, 'Library/Application Support/Claude')
+        : process.platform === 'win32'
+            ? join(process.env.APPDATA ?? join(home, 'AppData/Roaming'), 'Claude')
+            : join(home, '.config/Claude');
+    const [claude, desktop, cursor, hermes, codex] = await Promise.all([
+        onPath('claude'),
+        found(desktopConfig),
+        found(join(home, '.cursor')),
+        found(join(home, '.hermes')),
+        found(join(home, '.codex')),
+    ]);
+    console.log('Pick one at a time with the arrow keys and enter; add more after.');
+    const picked = await pickMany('Which agent may use your passes?', [
+        { name: `Claude Code${claude}`, value: 'claude-code' },
+        { name: `Claude Desktop${desktop}`, value: 'claude-desktop' },
+        { name: `Cursor${cursor}`, value: 'cursor' },
+        { name: `Hermes${hermes} (prints the config to paste)`, value: 'hermes' },
+        { name: `Codex${codex} (prints the config to paste)`, value: 'codex' },
+        { name: 'Something else (prints a generic MCP entry)', value: 'json' },
+    ], "That's all", false);
+    if (picked.length === 0) {
+        const finish = await select({
+            message: 'No agent picked. Finish without registering any?',
+            choices: [
+                { name: 'Go back and pick one', value: false },
+                { name: 'Finish; I will run connect later', value: true },
+            ],
+        });
+        if (!finish)
+            return chooseClients();
+    }
+    return picked;
+}
+program
+    .command('connect')
+    .description("Register the signer with an agent client. By default the stdio server over every pass on this machine, which the client starts when it needs it. --session registers one session's running HTTP signer (serve) instead.")
+    .option('--session <directory>')
+    .option('--client <client>', `one of ${CLIENTS.join(', ')}; asked when omitted`)
+    .action(async (o) => {
+    if (o.client && !CLIENTS.includes(o.client))
+        throw new Error(`Unknown client '${o.client}'`);
+    let http = null;
+    if (o.session) {
+        const store = await SessionStore.open(resolve(o.session));
+        if (!store.state.active)
+            throw new Error('Authorize this session in the wallet first');
+        const { mcpUrl } = JSON.parse(await readFile(join(store.directory, 'runtime.json'), 'utf8'));
+        http = { url: mcpUrl, headers: { Authorization: `Bearer ${await store.mcpToken()}` } };
+    }
+    const clients = o.client ? [o.client] : await chooseClients();
+    for (const client of clients)
+        await registerClient(client, http);
+    if (!http)
+        console.log('\nDone. Open the agent and tell it what to do with your money; it proposes the pass, you review and sign in your wallet, and it acts within the rules. Restart the agent after upgrading this package so it loads the new server.');
+});
+if (process.argv[1] && /(?:^|\/)cli\.(?:ts|js)$/.test(process.argv[1])) {
+    program.parseAsync().catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}

package/dist/describe.js

@@ -0,0 +1,352 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * One rendering of the rules for every surface. The chat, the review page and the status
+ * report all print these rows, so the text the owner approves is the text the wallet page
+ * shows. Browser-safe: no Node imports.
+ */
+import { bcs } from '@mysten/sui/bcs';
+import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
+import { priceDisplay, sameCoin, showCoin, SUI, } from './domain.js';
+const healthFactor = (ray) => (Number(BigInt(ray) / 10n ** 25n) / 100).toFixed(2);
+/** The reviewed rules, or the installed policies once `live` is read from chain. */
+export function describePolicy(d, p, live = null) {
+    const show = (coin, value) => showCoin(d, coin, value);
+    const symbol = (coin) => d.coins.find((c) => sameCoin(c.type, coin))?.symbol ?? coin;
+    const poolName = (id) => {
+        const pool = d.pools.find((x) => x.poolId === id);
+        return pool ? (pool.venue === 'deepbook' ? 'DeepBook' : 'Cetus') : id;
+    };
+    const rows = [
+        {
+            label: 'Allowed actions',
+            value: [
+                p.transfers.length && 'Transfers',
+                p.swaps.length && 'Swaps',
+                p.lending.length &&
+                    (p.lending.some((l) => l.allowBorrow) ? 'Lending and borrowing' : 'Lending'),
+                p.staking && 'Staking',
+            ]
+                .filter(Boolean)
+                .join(' + '),
+        },
+    ];
+    for (const t of p.transfers) {
+        const l = live?.transfers.find((x) => sameCoin(x.coinType, t.coin));
+        rows.push({
+            label: `Pay ${symbol(t.coin)} to`,
+            value: (l?.recipients ?? t.recipients).map((r) => `${r.name} → ${r.address}`).join('\n'),
+        }, {
+            label: `${symbol(t.coin)} per transfer · per UTC day`,
+            value: `${show(t.coin, l?.perTransfer ?? t.perTransfer)} · ${show(t.coin, l?.daily ?? t.daily)}`,
+        });
+    }
+    for (const sw of p.swaps) {
+        const l = live?.swaps.find((x) => sameCoin(x.coinIn, sw.coinIn) && sameCoin(x.coinOut, sw.coinOut));
+        const minPrice = l?.minPrice ?? sw.minPrice;
+        rows.push({
+            label: `Sell ${symbol(sw.coinIn)} for ${symbol(sw.coinOut)} on`,
+            value: (l?.venues ?? sw.pools).map(poolName).join(', '),
+        }, {
+            label: `${symbol(sw.coinIn)} per trade · per UTC day`,
+            value: `${show(sw.coinIn, l?.perTrade ?? sw.perTrade)} · ${show(sw.coinIn, l?.daily ?? sw.daily)}`,
+        }, {
+            label: 'Lowest price accepted',
+            value: `${priceDisplay(d, sw.coinIn, sw.coinOut, minPrice)} ${symbol(sw.coinOut)} per ${symbol(sw.coinIn)}`,
+        });
+    }
+    for (const le of p.lending) {
+        const l = live?.lending.find((x) => sameCoin(x.coinType, le.coin));
+        rows.push({
+            label: `NAVI ${le.allowBorrow ? 'borrowing' : 'collateral'} in ${symbol(le.coin)}, per action · per UTC day`,
+            value: `${show(le.coin, l?.perAction ?? le.perAction)} · ${show(le.coin, l?.daily ?? le.daily)}`,
+        });
+        const floor = l ? healthFactor(l.minHealthFactor) : le.minHealthFactor?.toFixed(2);
+        if (floor && floor !== '0.00')
+            rows.push({ label: `Health factor kept above (${symbol(le.coin)})`, value: floor });
+    }
+    if (p.staking) {
+        const l = live?.staking[0];
+        const validators = l?.validators ?? p.staking.validators;
+        rows.push({
+            label: 'Stake SUI with',
+            value: validators.length ? validators.join('\n') : 'Any active validator',
+        }, {
+            label: 'SUI per stake · per UTC day',
+            value: `${show(SUI, l?.perStake ?? p.staking.perStake)} · ${show(SUI, l?.daily ?? p.staking.daily)}`,
+        });
+    }
+    return rows;
+}
+const utc = new Intl.DateTimeFormat('en-US', {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+    timeZone: 'UTC',
+});
+/** Everything the owner is about to sign, rules first. Coins stay in the owner's address. */
+export function describeSetup(d, setup) {
+    return [
+        ...describePolicy(d, setup.policy),
+        {
+            label: 'Authorization ends',
+            value: `${utc.format(setup.expiresMs)} UTC (${setup.ttlMs / 86_400_000} ${setup.ttlMs === 86_400_000 ? 'day' : 'days'}); you can revoke earlier`,
+        },
+        {
+            label: 'Agent may ever withdraw (lifetime caps)',
+            value: Object.entries(setup.allowances)
+                .map(([coin, cap]) => showCoin(d, coin, cap))
+                .join(' · '),
+        },
+        {
+            label: 'Gas allowance, lifetime · per UTC day',
+            value: `${showCoin(d, SUI, setup.gasCap)} · ${showCoin(d, SUI, setup.gasDaily)}`,
+        },
+        {
+            label: 'Agent gas stipend (outside the rules)',
+            value: showCoin(d, SUI, setup.gasAmount),
+        },
+    ];
+}
+export const renderRows = (rows) => rows.map(({ label, value }) => `- ${label}: ${value.replaceAll('\n', '; ')}`).join('\n');
+const OWNER_ONLY = new Set([
+    'deposit_object',
+    'withdraw_object',
+    'navi_open',
+    'destroy',
+    'issue',
+    'rotate_allowance',
+    'add_policy',
+    'remove_policy',
+    'set_agent',
+    'revoke_agent',
+]);
+/**
+ * Reads the agent's transaction back in the owner's terms: the action it attempted, where
+ * value went and, for a refusal, the rule that stopped it.
+ */
+export function describeAttempt(d, sessionAddress, recipients, tx) {
+    const { inputs, commands } = tx.transaction;
+    const coin = (type, value) => type ? showCoin(d, normalizeType(type), value) : `${value} base units of an unknown coin`;
+    const input = (arg) => arg && typeof arg === 'object' && 'Input' in arg
+        ? inputs[arg.Input]
+        : undefined;
+    const pure = (arg, kind) => {
+        const i = input(arg);
+        if (!i || !('Pure' in i) || !i.Pure)
+            return null;
+        try {
+            const bytes = fromBase64(i.Pure.bytes);
+            return kind === 'u64'
+                ? bcs.u64().parse(bytes)
+                : kind === 'address'
+                    ? normalizeSuiAddress(bcs.Address.parse(bytes))
+                    : bcs.string().parse(bytes);
+        }
+        catch {
+            return null;
+        }
+    };
+    const object = (arg) => {
+        const i = input(arg);
+        if (!i || !('Object' in i) || !i.Object)
+            return null;
+        const o = i.Object;
+        const id = 'SharedObject' in o
+            ? o.SharedObject?.objectId
+            : 'ImmOrOwnedObject' in o
+                ? o.ImmOrOwnedObject?.objectId
+                : undefined;
+        return id ? normalizeSuiAddress(id) : null;
+    };
+    /** A spend names its amount in a withdrawal input rather than a pure argument. */
+    const withdrawal = (arg) => {
+        const i = input(arg);
+        if (!i || !('FundsWithdrawal' in i) || !i.FundsWithdrawal)
+            return null;
+        const w = i.FundsWithdrawal;
+        return w.reservation?.MaxAmountU64 ?? null;
+    };
+    const amount0 = (call) => {
+        const v = withdrawal(call.arguments[1]);
+        return v === null ? 'SUI' : coin(SUI, v);
+    };
+    const venue = (pool) => {
+        const known = d.pools.find((p) => p.poolId === pool);
+        return known ? (known.venue === 'deepbook' ? 'DeepBook' : 'Cetus') : 'a pool you did not list';
+    };
+    // Calls name the package version they ran on: the original or any upgrade of it.
+    const ours = (pkg) => [d.packageId, d.publishedAt].some((p) => normalizeSuiAddress(p) === normalizeSuiAddress(pkg));
+    const calls = commands.flatMap((c) => 'MoveCall' in c && c.MoveCall ? [c.MoveCall] : []);
+    // The entry point is the call into `pass`; helpers such as `staking::stake_key` only build its
+    // arguments.
+    const main = calls.find((c) => ours(c.package) && c.module === 'pass') ??
+        calls.find((c) => ours(c.package)) ??
+        calls[0];
+    let what = 'Custom transaction';
+    let recipient = null;
+    if (main && ours(main.package)) {
+        const [t0, t1] = main.typeArguments, a = main.arguments;
+        // Spending entries take (pass, config, allowance, withdrawal, ...): the amount sits in the
+        // withdrawal input at slot 3. navi_withdraw and navi_borrow take no withdrawal.
+        const amount = (i, type = t0) => {
+            const v = pure(a[i], 'u64') ?? withdrawal(a[i]);
+            return v === null ? 'an amount' : coin(type, v);
+        };
+        switch (main.function) {
+            case 'transfer':
+                recipient = pure(a[a.length - 2], 'string');
+                what = `Pay ${amount(3)} to ${recipient ? `"${recipient}"` : 'a recipient'}`;
+                break;
+            case 'deepbook_base_to_quote':
+                what = `Sell ${amount(3)} on ${venue(object(a[4]))}, accepting at least ${amount(5, t1)}`;
+                break;
+            case 'deepbook_quote_to_base':
+                what = `Sell ${amount(3, t1)} on ${venue(object(a[4]))}, accepting at least ${amount(5)}`;
+                break;
+            case 'cetus_a_to_b':
+                what = `Sell ${amount(3)} on ${venue(object(a[5]))}, accepting at least ${amount(6, t1)}`;
+                break;
+            case 'cetus_b_to_a':
+                what = `Sell ${amount(3, t1)} on ${venue(object(a[5]))}, accepting at least ${amount(6)}`;
+                break;
+            case 'navi_supply':
+                what = `Supply ${amount(3)} to NAVI`;
+                break;
+            case 'navi_repay':
+                what = `Repay ${amount(3)} to NAVI`;
+                break;
+            case 'navi_withdraw':
+                what = `Withdraw ${amount(7)} from NAVI`;
+                break;
+            case 'navi_borrow':
+                what = `Borrow ${amount(7)} from NAVI`;
+                break;
+            case 'stake': {
+                const validator = pure(a[5], 'address');
+                // `stake` has no type argument: it is always SUI.
+                what = `Stake ${amount(3, SUI)} with ${validator ? `validator ${short(validator)}` : 'a validator'}`;
+                break;
+            }
+            case 'unstake': {
+                const stake = pure(a[3], 'address');
+                what = `Unstake ${stake ? short(stake) : 'a stake'} back to your balance`;
+                break;
+            }
+            default:
+                what = OWNER_ONLY.has(main.function)
+                    ? `Call the owner-only ${main.module}::${main.function}`
+                    : `Call ${main.module}::${main.function}`;
+        }
+    }
+    else if (main &&
+        normalizeSuiAddress(main.package) === normalizeSuiAddress('0x2') &&
+        main.module === 'allowance' &&
+        main.function === 'balance_spend') {
+        what = `Top up the agent's gas with ${amount0(main)}`;
+    }
+    else if (main) {
+        what = `Call ${main.module}::${main.function}`;
+    }
+    const names = new Map(recipients.map((r) => [normalizeSuiAddress(r.address), r.name]));
+    const self = normalizeSuiAddress(sessionAddress);
+    const moved = tx.status.success
+        ? tx.balanceChanges
+            .filter((c) => BigInt(c.amount) > 0n && normalizeSuiAddress(c.address) !== self)
+            .map((c) => `${coin(c.coinType, c.amount)} → ${names.get(normalizeSuiAddress(c.address)) ?? short(c.address)}`)
+        : [];
+    return {
+        digest: tx.digest,
+        timestampMs: tx.timestampMs,
+        success: tx.status.success,
+        what,
+        why: tx.status.success ? null : describeRefusal(d, tx.status.error, recipient),
+        moved,
+    };
+}
+const short = (address) => `${address.slice(0, 8)}…${address.slice(-6)}`;
+const normalizeType = (type) => type.replace(/^0x0*([0-9a-f]+)::/i, (_, a) => `${normalizeSuiAddress(a)}::`);
+/** The owner's rule behind an abort, from the codes the policy modules define. */
+export function describeRefusal(d, error, recipient) {
+    const abort = error.MoveAbort;
+    if (!abort?.location?.module)
+        return error.message;
+    const code = Number(abort.cleverError?.errorCode ?? abort.abortCode);
+    const where = `${abort.location.module} abort ${code}`;
+    const pkg = normalizeSuiAddress(abort.location.package ?? '0x0');
+    // The framework and the system package have their own reasons; anything else is a protocol.
+    const system = {
+        allowance: {
+            3: "Over the lifetime cap of the owner's allowance for this coin (checked before the daily limit, so when the two are equal the day is used up as well)",
+            4: "Over the allowance's daily window",
+        },
+        validator_set: { 10: 'Below the 1 SUI minimum stake', 0: 'Not an active validator' },
+    };
+    if (pkg === normalizeSuiAddress('0x2') || pkg === normalizeSuiAddress('0x3')) {
+        const reason = system[abort.location.module]?.[code];
+        return reason ? `${reason} (${where})` : `Refused in ${where}`;
+    }
+    // A protocol's own refusal is not one of the owner's rules; say so, and name the ones an agent
+    // meets on NAVI (lending_core/sources/error.move).
+    if (pkg !== normalizeSuiAddress(d.packageId)) {
+        const navi = {
+            1500: 'NAVI is paused',
+            1502: 'NAVI has no fresh oracle price for this asset; the price must be refreshed in the same transaction',
+            1503: 'NAVI rejected the amount',
+            1506: 'NAVI pool has insufficient balance',
+            1508: 'NAVI no longer accepts this entry point; the pass must call its current one',
+            1600: 'NAVI finds the position unhealthy',
+            1601: 'the position holds no collateral',
+            1602: 'the position has no debt to repay',
+            1603: 'the collateral does not cover that borrow (loan-to-value)',
+            1604: "NAVI's deposit cap for this asset is reached",
+            1605: "NAVI's borrow cap for this asset is reached",
+        };
+        const known = navi[code];
+        return known
+            ? `Refused by NAVI, not by your rules: ${known} (${where})`
+            : `Refused inside the protocol, not by your rules (${where}): ${error.message}`;
+    }
+    const reasons = {
+        transfer_policy: {
+            0: `${recipient ? `"${recipient}"` : 'That recipient'} is not a recipient you named`,
+            1: 'Over your per-transfer limit',
+            2: 'Zero amount',
+        },
+        meter: { 0: 'Over your daily limit' },
+        swap_policy: {
+            0: 'Not a pool you listed',
+            1: 'Over your per-trade limit',
+            3: "Below the agent's own minimum output",
+            4: 'Below your price floor',
+            8: 'The venue filled nothing (order under its minimum size)',
+        },
+        lending_policy: {
+            0: 'Not the NAVI pool or asset you chose',
+            1: 'Borrowing is not allowed',
+            3: 'Over your per-action limit',
+        },
+        navi: {
+            0: 'Your health-factor floor would be breached',
+            2: 'The NAVI account is not in the pass; you reclaimed it',
+        },
+        staking_policy: {
+            0: 'Not a validator you listed',
+            1: 'Over your per-stake limit',
+            2: 'Zero amount',
+        },
+        staking: { 0: 'No such stake is held by the pass' },
+        pass: {
+            1: 'Not an allowance issued for this pass',
+            2: 'No such object is held by the pass',
+            7: 'This entry was retired by a package upgrade; use the current SDK',
+        },
+        control: {
+            0: 'Only your wallet can do this',
+            1: 'This key is not your agent',
+            2: "Your agent's access was revoked or has expired",
+        },
+        policies: { 0: 'No rule allows this coin or action' },
+    };
+    const reason = reasons[abort.location.module]?.[code];
+    return reason ? `${reason} (${where})` : `Refused in ${where}`;
+}