@mysten-incubation/sui-agent-pass 0.1.8 → 0.1.10

package/deployments/mainnet.json

@@ -35,12 +35,14 @@
 	"protocols": {
 		"deepbook": {
 			"packageId": "0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809",
-			"publishedAt": "0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748"
+			"publishedAt": "0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748",
+			"indexerUrl": "https://deepbook-indexer.mainnet.mystenlabs.com"
 		},
 		"cetus": {
 			"packageId": "0x1eabed72c53feb3805120a081dc15963c204dc8d091542592abaf7a35689b2fb",
 			"publishedAt": "0x260693ec785a6e6c9d81d58c7d2ff72f1288ae0fa6a9725abe05a6478b11f084",
-			"configId": "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f"
+			"configId": "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f",
+			"apiUrl": "https://api-sui.cetus.zone"
 		},
 		"navi": {
 			"packageId": "0x66c91a8560cd64d73d93dd1ec7b61f3f21ad2f66553dd3d7038ca69255479bb7",

package/dist/chain.js

@@ -661,6 +661,70 @@ export async function withMarketFacts(client, d, needs) {
     }
     return { ...d, coins, pools };
 }
+/**
+ * Pools on DeepBook and Cetus that trade `coin` (against `other` when given), largest Cetus TVL
+ * first. The venues' public listings only nominate candidates; each one is then read from chain
+ * by `withMarketFacts`, which drops anything that is not a pool of those coins. Returns the
+ * deployment extended with the pools and coins found.
+ */
+export async function findPools(client, d, coin, other) {
+    const want = normalizeStructTag(coin), with_ = other ? normalizeStructTag(other) : null;
+    const fits = (a, b) => {
+        const [x, y] = [normalizeStructTag(a), normalizeStructTag(b)];
+        return (x === want && (!with_ || y === with_)) || (y === want && (!with_ || x === with_));
+    };
+    const candidates = new Map();
+    for (const p of d.pools)
+        if (fits(p.coinA, p.coinB))
+            candidates.set(p.poolId, null);
+    const { deepbook, cetus } = d.protocols;
+    const listings = await Promise.all([
+        deepbook.indexerUrl
+            ? fetch(`${deepbook.indexerUrl}/get_pools`, { signal: AbortSignal.timeout(8_000) })
+                .then((r) => r.json())
+                .then((all) => all
+                .filter((p) => fits(p.base_asset_id, p.quote_asset_id))
+                .map((p) => [p.pool_id, null]))
+                .catch(() => [])
+            : [],
+        cetus.apiUrl
+            ? fetch(`${cetus.apiUrl}/v3/sui/clmm/stats_pools`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    filter: '',
+                    sortBy: 'tvl',
+                    sortOrder: 'desc',
+                    limit: 20,
+                    offset: 0,
+                    coinTypes: [want],
+                }),
+                signal: AbortSignal.timeout(8_000),
+            })
+                .then((r) => r.json())
+                .then((r) => (r.data?.list ?? [])
+                .filter((p) => fits(p.coinA.coinType, p.coinB.coinType))
+                .map((p) => [p.pool, p.tvl ?? null]))
+                .catch(() => [])
+            : [],
+    ]);
+    for (const [id, tvl] of listings.flat())
+        candidates.set(normalizeSuiAddress(id), tvl);
+    const ranked = [...candidates]
+        .sort(([, a], [, b]) => Number(b ?? 0) - Number(a ?? 0))
+        .slice(0, 10);
+    let extended = d;
+    const found = [];
+    for (const [id, tvl] of ranked) {
+        const next = await withMarketFacts(client, extended, { coins: [], pools: [id] }).catch(() => null);
+        const pool = next?.pools.find((p) => p.poolId === normalizeSuiAddress(id));
+        if (!next || !pool || !fits(pool.coinA, pool.coinB))
+            continue;
+        extended = next;
+        found.push({ pool, tvlUsd: tvl === null ? null : Number(tvl).toFixed(0) });
+    }
+    return { d: extended, found };
+}
 function structTagString(t) {
     const params = t.typeParams.map((p) => (typeof p === 'string' ? p : structTagString(p)));
     return `${t.address}::${t.module}::${t.name}${params.length ? `<${params.join(',')}>` : ''}`;

package/dist/describe.js

@@ -277,6 +277,8 @@ const normalizeType = (type) => type.replace(/^0x0*([0-9a-f]+)::/i, (_, 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 (error.message === 'InsufficientBalanceForWithdraw')
+        return "The owner's address balance does not hold enough of this coin right now. This is not one of the owner's rules: the action can run once the balance covers it (InsufficientBalanceForWithdraw)";
     if (!abort?.location?.module)
         return error.message;
     const code = Number(abort.cleverError?.errorCode ?? abort.abortCode);

package/dist/domain.js

@@ -164,10 +164,20 @@ export const DeploymentSchema = z
             packageId: address,
             /** The latest upgrade, for calls made from a PTB; the original is version-gated. */
             publishedAt: address,
+            /** DeepBook's public indexer, which lists every pool; used only to find candidates. */
+            indexerUrl: z.string().url().optional(),
         })
             .strict(),
         /** `packageId` defines the pool type; `publishedAt` is the upgrade that answers calls. */
-        cetus: z.object({ packageId: address, publishedAt: address, configId: address }).strict(),
+        cetus: z
+            .object({
+            packageId: address,
+            publishedAt: address,
+            configId: address,
+            /** Cetus's public API, which lists pools by coin; used only to find candidates. */
+            apiUrl: z.string().url().optional(),
+        })
+            .strict(),
         navi: z
             .object({
             /** The package that defines `account::AccountCap`, which the pass holds. */
@@ -399,25 +409,45 @@ export function drawable(setup) {
     return Object.fromEntries(Object.entries(need).map(([c, v]) => [c, v.toString()]));
 }
 /**
- * Allowances draw only from the owner's address balance, never from coin objects. What the
- * authorization converts from the owner's coins into their address balance is, per coin, the
- * shortfall between what the rules can draw (`drawable`) and what that balance already holds.
- * Converted coins stay the owner's to spend.
+ * Allowances draw only from the owner's address balance, never from coin objects. The
+ * authorization converts coin objects into that balance, per coin, as far as the rules can draw
+ * (`drawable`) and the owner has them; the caps are limits, not money that must exist at signing.
+ * SUI keeps the stipend and the fee reserve in coin objects for the transaction itself. `mintable`
+ * is a demo coin the transaction mints instead, converted in full. Converted coins stay the
+ * owner's to spend.
+ */
+export function conversion(setup, held, mintable = null) {
+    const of = (coin) => held[normalizeStructTag(coin)];
+    return Object.fromEntries(Object.entries(drawable(setup)).map(([coin, want]) => {
+        const short = BigInt(want) - BigInt(of(coin)?.addressBalance ?? '0');
+        if (short <= 0n)
+            return [coin, '0'];
+        if (mintable && sameCoin(mintable, coin))
+            return [coin, short.toString()];
+        let spare = BigInt(of(coin)?.coinBalance ?? '0');
+        if (sameCoin(coin, SUI))
+            spare -= BigInt(setup.gasAmount) + OWNER_FEE_RESERVE;
+        return [coin, (spare <= 0n ? 0n : short < spare ? short : spare).toString()];
+    }));
+}
+/**
+ * What the rules can draw beyond what the address balance will hold right after signing, per
+ * coin. Not an error: withdrawals work while the balance covers them, and swap proceeds land in
+ * it. Coins with nothing uncovered are left out.
  */
-export function conversion(setup, held) {
-    const have = (coin) => BigInt(held[normalizeStructTag(coin)] ?? '0');
-    return Object.fromEntries(Object.entries(drawable(setup)).map(([coin, want]) => [
-        coin,
-        (BigInt(want) > have(coin) ? BigInt(want) - have(coin) : 0n).toString(),
-    ]));
+export function uncovered(setup, held, mintable = null) {
+    const convert = conversion(setup, held, mintable);
+    return Object.fromEntries(Object.entries(drawable(setup)).flatMap(([coin, want]) => {
+        const covered = BigInt(held[normalizeStructTag(coin)]?.addressBalance ?? '0') + BigInt(convert[coin] ?? '0');
+        return covered >= BigInt(want) ? [] : [[coin, { drawable: want, covered: covered.toString() }]];
+    }));
 }
 /**
- * SUI the owner must hold in total to sign, address balance and coin objects together: what the
- * rules may draw, the stipend and a fee reserve. Gas comes from either side, so nothing has to
- * be a coin object; the authorization consolidates what it touches into the address balance.
+ * SUI the owner must hold to sign, address balance and coin objects together: only what this
+ * transaction moves, the agent's gas stipend, plus a fee reserve. The caps need nothing up front.
  */
 export function requiredSui(setup) {
-    return (BigInt(drawable(setup)[SUI]) + BigInt(setup.gasAmount) + OWNER_FEE_RESERVE).toString();
+    return (BigInt(setup.gasAmount) + OWNER_FEE_RESERVE).toString();
 }
 /** Set aside for the owner's own transaction fees when checking what they hold. */
 export const OWNER_FEE_RESERVE = 50000000n;

package/dist/plugin.js

@@ -20,9 +20,9 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { Transaction } from '@mysten/sui/transactions';
 import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
 import { z } from 'zod';
-import { clientFor, deepbookSizes, quoteSwap, readAllHoldings, readStatus, withMarketFacts, } from './chain.js';
+import { clientFor, deepbookSizes, findPools, quoteSwap, readAllHoldings, readHoldings, readStatus, withMarketFacts, } from './chain.js';
 import { describePolicy, describeSetup, renderRows } from './describe.js';
-import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, poolsFor, recipientName, sameCoin, SetupSchema, showCoin, units, VenueSchema, } from './domain.js';
+import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, poolsFor, recipientName, requiredSui, sameCoin, SetupSchema, showCoin, SUI, uncovered, units, VenueSchema, } from './domain.js';
 import { passesByAgent } from './explorer.js';
 import { passEnded, returnGasFloat } from './float.js';
 import { failure, INSTRUCTIONS, registerDocs, result, serverInfo, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
@@ -233,7 +233,7 @@ const rulesInput = {
         pools: z
             .array(address)
             .optional()
-            .describe('pool object ids for a pair the deployment does not list (a DeepBook or Cetus pool holding exactly these two coins); verified on chain'),
+            .describe('pool ids from find_pools for a pair the network does not list; never ask the owner for one. Verified on chain'),
         perTrade: decimal.describe('sold coin per trade'),
         daily: decimal.describe('sold coin per UTC day'),
         limitPrice: decimal.describe("the owner's price limit. With a stablecoin on one side it is that stablecoin per one of the other coin: the most paid when buying, the least accepted when selling. Otherwise it is bought coin per one sold coin, the least accepted. Required, above 0, and only the owner sets it: ask them, showing the pool's current price from list_passes"),
@@ -311,7 +311,7 @@ async function toSetup(client, d0, input) {
                     (!sw.pools || sw.pools.some((id) => normalizeSuiAddress(id) === p.poolId)));
                 if (!pools.length)
                     throw new Error(d.pools.length
-                        ? `No pool trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}${sw.pools ? ` among ${sw.pools.join(', ')}` : ''}; name a DeepBook or Cetus pool id for this pair in pools`
+                        ? `No pool trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}${sw.pools ? ` among ${sw.pools.join(', ')}` : ''}; look one up with find_pools and pass its id in pools`
                         : `Swaps are not offered on ${d.network}: it lists no pools. Propose a pass on a network that does, or leave swaps out`);
                 return {
                     coinIn,
@@ -405,6 +405,20 @@ export async function forgetSession(directory) {
     await registry.all();
     return registry.forget(basename(resolve(directory)));
 }
+/**
+ * What a pool pays for ten units of its non-stable coin (coinA when neither or both are
+ * stablecoins), quoted like a rule's price; ten clears DeepBook's minimum order.
+ */
+async function poolPrice(d, p) {
+    const flip = isStable(coinInfo(d, p.coinA).symbol) && !isStable(coinInfo(d, p.coinB).symbol);
+    const a = coinInfo(d, flip ? p.coinB : p.coinA), b = coinInfo(d, flip ? p.coinA : p.coinB);
+    const amountIn = (10n * 10n ** BigInt(a.decimals)).toString();
+    const q = await quoteSwap(clientFor(d), d, p, a.type, amountIn).catch(() => null);
+    if (!q || q.amountOut === '0')
+        return {};
+    const perUnit = (BigInt(q.amountOut) * 10n ** BigInt(a.decimals)) / BigInt(q.amountIn);
+    return { price: `${display(perUnit.toString(), b.decimals)} ${b.symbol} per ${a.symbol}` };
+}
 export function createPluginMcp(registry) {
     const server = new McpServer({ name: 'agent-pass', version: '0.1.0' }, {
         instructions: `${INSTRUCTIONS} This server also runs the owner flow: propose_authorization turns reviewed rules into a pass proposal and opens the owner's wallet page; session_info (with wait) reports when the owner has signed and the on-chain policies match; revoke_pass reopens the owner page for revocation. Show the owner the exact "rules" text returned by propose_authorization before they sign; never paraphrase amounts.`,
@@ -420,30 +434,18 @@ export function createPluginMcp(registry) {
         annotations: { readOnlyHint: true },
     }, async ({ owner }) => {
         const path = registry.deploymentPath();
-        // What the pool pays for ten units of its non-stable coin (coinA when neither or both are
-        // stablecoins), quoted like a rule's price; ten clears DeepBook's minimum order.
-        const price = async (d, p) => {
-            const flip = isStable(coinInfo(d, p.coinA).symbol) && !isStable(coinInfo(d, p.coinB).symbol);
-            const a = coinInfo(d, flip ? p.coinB : p.coinA), b = coinInfo(d, flip ? p.coinA : p.coinB);
-            const amountIn = (10n * 10n ** BigInt(a.decimals)).toString();
-            const q = await quoteSwap(clientFor(d), d, p, a.type, amountIn).catch(() => null);
-            if (!q || q.amountOut === '0')
-                return {};
-            const perUnit = (BigInt(q.amountOut) * 10n ** BigInt(a.decimals)) / BigInt(q.amountIn);
-            return { price: `${display(perUnit.toString(), b.decimals)} ${b.symbol} per ${a.symbol}` };
-        };
         const markets = async (d) => ({
             network: d.network,
             coins: d.coins,
             pools: await Promise.all(d.pools.map(async (p) => ({
                 venue: p.venue,
                 pair: `${coinInfo(d, p.coinA).symbol}/${coinInfo(d, p.coinB).symbol}`,
-                ...(await price(d, p)),
+                ...(await poolPrice(d, p)),
             }))),
             lending: Object.keys(d.protocols.navi.reserves).map((c) => coinInfo(d, c).symbol),
             ...(d.pools.length || Object.keys(d.protocols.navi.reserves).length
                 ? {
-                    otherCoins: 'These are the coins and pools this package lists, not all it can use. Any other coin the owner holds goes in a transfer or swap rule by its full type; a swap of it also needs, in pools, the id of a DeepBook or Cetus pool holding exactly that pair. The server reads the coin and the pool from chain. Lending stays with the listed coins.',
+                    otherCoins: 'These are the coins and pools this package lists, not all it can use. Any other coin the owner holds goes in a transfer or swap rule by its full type; for a swap, find_pools looks up the DeepBook and Cetus pools for it, and their ids go in pools. Never ask the owner for a pool id. The server reads the coin and the pool from chain. Lending stays with the listed coins.',
                 }
                 : {
                     note: 'Transfers and staking only: this network lists no pools and no NAVI reserves, so swap and lending rules are refused here.',
@@ -469,8 +471,40 @@ export function createPluginMcp(registry) {
             networks: [...own, ...bundled.filter((b) => !own.some((o) => o.network === b.network))],
         });
     });
+    server.registerTool('find_pools', {
+        description: "Find the DeepBook and Cetus pools that trade a coin, optionally against one other coin, for a swap rule. Each result is read from chain and carries its venue, id, pair, both coin types, Cetus TVL in USD when known and the pool's current price. Use it instead of asking the owner for a pool; prefer the deepest pool, and when the coin is ambiguous show the owner their balance of it and this price so they can confirm it is the right token.",
+        inputSchema: {
+            coin: symbol.describe('the coin, by symbol when list_passes lists it, else by full type'),
+            with: symbol.optional().describe('the other coin of the pair, same form; any when omitted'),
+            network: z
+                .enum(['mainnet', 'testnet', 'devnet', 'localnet'])
+                .optional()
+                .describe('defaults to the network a new pass would use'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ coin, with: other, network }) => {
+        try {
+            const d0 = await registry.deployment(undefined, network);
+            const type = (s) => (/::/.test(s) ? s : coinBySymbol(d0, s).type);
+            const { d, found } = await findPools(clientFor(d0), d0, type(coin), other ? type(other) : undefined);
+            const priced = await Promise.all(found.map(async ({ pool, tvlUsd }) => ({
+                venue: pool.venue,
+                poolId: pool.poolId,
+                pair: `${coinInfo(d, pool.coinA).symbol}/${coinInfo(d, pool.coinB).symbol}`,
+                coinA: pool.coinA,
+                coinB: pool.coinB,
+                tvlUsd,
+                ...(await poolPrice(d, pool)),
+            })));
+            // A pool that cannot price ten units holds too little to trade against.
+            return result({ network: d.network, pools: priced.filter((p) => 'price' in p) });
+        }
+        catch (error) {
+            return failure(error, 'Pool lookup failed');
+        }
+    });
     server.registerTool('propose_authorization', {
-        description: "Create a new pass proposal from rules in human units (coins by symbol when list_passes lists them for the network, else by full type, with pool ids for a pair the network list lacks; amounts as decimal strings) and open the owner's review page, where they connect Slush, check the same rules and sign one transaction. That transaction creates the pass, converts the owner's coins into their own address balance as far as the caps need, issues the allowances the agent will draw on, installs the policies and gives the new agent key its gas; the owner's coins never enter the pass. Returns the exact rules text to show the owner, the review URL and the session address. Nothing is on chain until the owner signs; poll session_info with wait afterwards.",
+        description: "Create a new pass proposal from rules in human units (coins by symbol when list_passes lists them for the network, else by full type, with pool ids from find_pools for a pair the network list lacks; amounts as decimal strings) and open the owner's review page, where they connect Slush, check the same rules and sign one transaction. That transaction creates the pass, converts the owner's coins into their own address balance as far as the caps need, issues the allowances the agent will draw on, installs the policies and gives the new agent key its gas; the owner's coins never enter the pass. Returns the exact rules text to show the owner, the review URL and the session address. Nothing is on chain until the owner signs; poll session_info with wait afterwards.",
         inputSchema: {
             name: z
                 .string()
@@ -495,9 +529,12 @@ export function createPluginMcp(registry) {
                 .string()
                 .optional()
                 .describe('path of a private deployment.json; overrides network'),
+            owner: address
+                .optional()
+                .describe("the owner's address, when they gave it: adds warnings where the caps reach past what they hold, or when they cannot sign yet"),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ deployment, network, ...input }) => {
+    }, async ({ deployment, network, owner, ...input }) => {
         try {
             const d0 = await registry.deployment(deployment, network);
             const { setup, d } = await toSetup(clientFor(d0), d0, input);
@@ -523,6 +560,17 @@ export function createPluginMcp(registry) {
                         warnings.push(`DeepBook takes its fee from the input and fills nothing under its minimum order, so a sale needs at least ${showCoin(d, sw.coinIn, floor)} and this pass allows ${showCoin(d, sw.coinIn, sw.perTrade)}: no sale could ever happen. Propose again with Cetus added to venues or a larger perTrade, unless the owner wants exactly this.`);
                 }
             }
+            if (owner) {
+                const holdings = await readHoldings(clientFor(d), d, owner).catch(() => null);
+                if (holdings) {
+                    const sui = holdings[SUI];
+                    const total = BigInt(sui?.addressBalance ?? '0') + BigInt(sui?.coinBalance ?? '0');
+                    if (total < BigInt(requiredSui(setup)))
+                        warnings.push(`The owner holds ${showCoin(d, SUI, total.toString())} and signing needs ${showCoin(d, SUI, requiredSui(setup))} for the agent's gas stipend and the fee; they must add SUI before they can sign.`);
+                    for (const [coin, { drawable: most, covered }] of Object.entries(uncovered(setup, holdings, d.demoFaucet?.coin ?? null)))
+                        warnings.push(`The rules can draw up to ${showCoin(d, coin, most)} but the owner's address balance will hold ${showCoin(d, coin, covered)} after signing. Signing still works; each action runs only while the balance covers it, and swap proceeds that land there count. Tell the owner before they sign.`);
+                }
+            }
             return result({
                 pass: session.id,
                 sessionAddress: session.store.state.sessionAddress,

package/docs/PLAYBOOK.md

@@ -54,14 +54,17 @@ pool), so list Cetus as well when trades will be small. A network may list no po
 reserves; `list_passes` says so, and swap or lending rules are refused there.
 
 **Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
-package lists, not the only ones it can use. Name a listed coin by symbol. Name any other coin
-the owner holds by its full type, and for a swap give the id of a DeepBook or Cetus pool holding
-exactly that pair in `pools`. To find the type and the balance, ask the owner for their address
-and call `list_passes` with `owner`: it adds every coin that address holds per network. For the
-pool, ask the owner or look the pair up on the venue's own site. The server and the review page
-read such a coin's symbol and decimals and such a pool's venue from chain, never from you, and
-the page shows an unlisted coin with its type so the owner can tell a look-alike from the real
-one. Lending is limited to the coins the network lists as NAVI reserves.
+package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
+owner holds by its full type. To find its type and balance, ask the owner for their address and
+call `list_passes` with `owner`: it adds every coin that address holds per network. For a swap,
+find the pool with `find_pools`, which looks up DeepBook and Cetus, reads each pool from chain and
+quotes its current price; pick the deepest one for the pair and pass its id in `pools`. Never ask
+the owner for a pool id. When you are unsure you have the right token (several coins share a
+symbol, or the owner named it loosely), show the owner their balance of it and its current price
+and ask them to confirm. The server and the review page read a coin's symbol and decimals and a
+pool's venue from chain, never from you, and the page shows an unlisted coin with its type so
+the owner can tell a look-alike from the real one. Lending is limited to the coins the network
+lists as NAVI reserves.
 
 **Lifetime caps.** `caps` gives, per coin, the total the key may ever withdraw, for exactly the
 coins the rules spend (staking spends SUI). A daily limit may not exceed its coin's cap. Size
@@ -79,19 +82,25 @@ ask for something like "restake with a better validator".
 to the agent key, outside the rules. `gasCapSui` (default 0.1) is a separate allowance the key
 draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its daily limit.
 
-**What the owner needs.** Allowances draw only from the owner's address balance, never from coin
-objects. The review page reads both, and the signature converts coin objects into the address
-balance as far as each cap (plus `gasCapSui` for SUI) needs; the converted coins stay theirs. The
-owner needs that much in total, address balance and coin objects together, plus `gasSui` and fees.
+**What the owner needs.** Signing moves only the agent's gas stipend and pays the fee, so that is
+all the owner must hold, in SUI. The caps are limits on what the rules may draw later, not money
+needed now. Allowances draw only from the owner's address balance, never from coin objects; the
+signature converts the owner's coin objects into that balance as far as each cap needs and they
+have them, and the converted coins stay theirs. When a cap reaches past what the owner holds,
+signing still works: each action runs while the balance covers it, and swap proceeds landing
+there count right away, which is how a chain like TAKE to SUI to USDC funds its later legs. Pass
+`owner` to `propose_authorization` when you know the address, and tell the owner about any
+`warnings` it returns before they sign. An action refused because the balance was short is not
+one of the owner's rules; say so.
 
 Before you call anything, show the owner the rules you intend to propose as one short list and
 ask for a yes, unless they already stated every rule explicitly.
 
 ## 2. Propose the pass and wait for the signature
 
-`propose_authorization`, `propose_change`, `list_passes`, `revoke_pass` and `forget_pass` live on
-the stdio server (`agent-pass mcp`), which keeps every session on the machine. A per-session HTTP
-signer has only `session_info` and `sign_transaction`.
+`propose_authorization`, `propose_change`, `list_passes`, `find_pools`, `revoke_pass` and
+`forget_pass` live on the stdio server (`agent-pass mcp`), which keeps every session on the
+machine. A per-session HTTP signer has only `session_info` and `sign_transaction`.
 
 The pass goes on the network the owner names (`network`, one of `list_passes.networks`), else on
 the first network listed. A private publish of one's own takes a `deployment` path instead.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mysten-incubation/sui-agent-pass",
-	"version": "0.1.8",
+	"version": "0.1.10",
 	"type": "module",
 	"description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
 	"repository": {

package/skills/agent-pass/SKILL.md

@@ -59,14 +59,17 @@ pool), so list Cetus as well when trades will be small. A network may list no po
 reserves; `list_passes` says so, and swap or lending rules are refused there.
 
 **Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
-package lists, not the only ones it can use. Name a listed coin by symbol. Name any other coin
-the owner holds by its full type, and for a swap give the id of a DeepBook or Cetus pool holding
-exactly that pair in `pools`. To find the type and the balance, ask the owner for their address
-and call `list_passes` with `owner`: it adds every coin that address holds per network. For the
-pool, ask the owner or look the pair up on the venue's own site. The server and the review page
-read such a coin's symbol and decimals and such a pool's venue from chain, never from you, and
-the page shows an unlisted coin with its type so the owner can tell a look-alike from the real
-one. Lending is limited to the coins the network lists as NAVI reserves.
+package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
+owner holds by its full type. To find its type and balance, ask the owner for their address and
+call `list_passes` with `owner`: it adds every coin that address holds per network. For a swap,
+find the pool with `find_pools`, which looks up DeepBook and Cetus, reads each pool from chain and
+quotes its current price; pick the deepest one for the pair and pass its id in `pools`. Never ask
+the owner for a pool id. When you are unsure you have the right token (several coins share a
+symbol, or the owner named it loosely), show the owner their balance of it and its current price
+and ask them to confirm. The server and the review page read a coin's symbol and decimals and a
+pool's venue from chain, never from you, and the page shows an unlisted coin with its type so
+the owner can tell a look-alike from the real one. Lending is limited to the coins the network
+lists as NAVI reserves.
 
 **Lifetime caps.** `caps` gives, per coin, the total the key may ever withdraw, for exactly the
 coins the rules spend (staking spends SUI). A daily limit may not exceed its coin's cap. Size
@@ -84,19 +87,25 @@ ask for something like "restake with a better validator".
 to the agent key, outside the rules. `gasCapSui` (default 0.1) is a separate allowance the key
 draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its daily limit.
 
-**What the owner needs.** Allowances draw only from the owner's address balance, never from coin
-objects. The review page reads both, and the signature converts coin objects into the address
-balance as far as each cap (plus `gasCapSui` for SUI) needs; the converted coins stay theirs. The
-owner needs that much in total, address balance and coin objects together, plus `gasSui` and fees.
+**What the owner needs.** Signing moves only the agent's gas stipend and pays the fee, so that is
+all the owner must hold, in SUI. The caps are limits on what the rules may draw later, not money
+needed now. Allowances draw only from the owner's address balance, never from coin objects; the
+signature converts the owner's coin objects into that balance as far as each cap needs and they
+have them, and the converted coins stay theirs. When a cap reaches past what the owner holds,
+signing still works: each action runs while the balance covers it, and swap proceeds landing
+there count right away, which is how a chain like TAKE to SUI to USDC funds its later legs. Pass
+`owner` to `propose_authorization` when you know the address, and tell the owner about any
+`warnings` it returns before they sign. An action refused because the balance was short is not
+one of the owner's rules; say so.
 
 Before you call anything, show the owner the rules you intend to propose as one short list and
 ask for a yes, unless they already stated every rule explicitly.
 
 ## 2. Propose the pass and wait for the signature
 
-`propose_authorization`, `propose_change`, `list_passes`, `revoke_pass` and `forget_pass` live on
-the stdio server (`agent-pass mcp`), which keeps every session on the machine. A per-session HTTP
-signer has only `session_info` and `sign_transaction`.
+`propose_authorization`, `propose_change`, `list_passes`, `find_pools`, `revoke_pass` and
+`forget_pass` live on the stdio server (`agent-pass mcp`), which keeps every session on the
+machine. A per-session HTTP signer has only `session_info` and `sign_transaction`.
 
 The pass goes on the network the owner names (`network`, one of `list_passes.networks`), else on
 the first network listed. A private publish of one's own takes a `deployment` path instead.