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

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

@@ -409,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) {
-    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 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()];
+    }));
 }
 /**
- * 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.
+ * 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 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 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, findPools, 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';
@@ -529,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);
@@ -557,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

@@ -82,10 +82,16 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mysten-incubation/sui-agent-pass",
-	"version": "0.1.9",
+	"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

@@ -87,10 +87,16 @@ 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.