@mysten-incubation/sui-agent-pass 0.1.30 → 0.1.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/agent.js CHANGED
@@ -13,7 +13,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
13
13
  import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
14
14
  import { Inputs, Transaction } from '@mysten/sui/transactions';
15
15
  import { fromBase64, normalizeStructTag, normalizeSuiAddress, toBase64 } from '@mysten/sui/utils';
16
- import { activeValidators, buildResignation, clientFor, quoteSwap, readAllowance, readControl, } from './chain.js';
16
+ import { activeValidators, clientFor, quoteSwap, readAllowance, readControl, resignCall, } from './chain.js';
17
17
  import { describeRefusal } from './describe.js';
18
18
  import { poolsFor, sameCoin, SUI, } from './domain.js';
19
19
  import { refreshNaviPrices } from './navi.js';
@@ -503,7 +503,9 @@ export function stake(i, amount, validator) {
503
503
  * The owner closes the pass from its page when they want the storage deposit back.
504
504
  */
505
505
  export function resign(i) {
506
- return buildResignation(i.deployment, i.active.passId);
506
+ const tx = new Transaction();
507
+ resignCall(tx, i.deployment, i.active.passId);
508
+ return tx;
507
509
  }
508
510
  /** Withdraw one held stake, principal and rewards, into the owner's balance. No allowance is drawn. */
509
511
  export function unstake(i, stakeId) {
package/dist/chain.js CHANGED
@@ -153,11 +153,9 @@ export const allowanceType = (coin) => `0x2::allowance::Allowance<0x2::balance::
153
153
  export const allowanceCapType = (coin) => `0x2::allowance::AllowanceCap<0x2::balance::Balance<${coin}>>`;
154
154
  export const policyType = (d, module, name, typeArguments) => normalizeStructTag(`${d.packageId}::${module}::${name}${typeArguments.length ? `<${typeArguments.join(',')}>` : ''}`);
155
155
  const typeNameTag = (name) => normalizeStructTag(`0x${name}`);
156
- /** The agent's own ending: `pass::resign`, signed by the session key; see `agent.resign`. */
157
- export function buildResignation(d, passId) {
158
- const tx = new Transaction();
156
+ /** The agent's own ending, `pass::resign`, added to a transaction the session key signs. */
157
+ export function resignCall(tx, d, passId) {
159
158
  tx.moveCall({ target: `${d.publishedAt}::pass::resign`, arguments: [tx.object(passId)] });
160
- return tx;
161
159
  }
162
160
  export async function readAuthorization(client, d, digest) {
163
161
  const result = await client.waitForTransaction({
package/dist/float.js CHANGED
@@ -22,12 +22,12 @@ export async function passClosed(client, passId) {
22
22
  * and sends the rest, so what stays behind is about one transaction's fee. Returns the digest,
23
23
  * or null when the float was dust.
24
24
  */
25
- export async function returnGasFloat(client, directory, sessionAddress, owner) {
25
+ export async function returnGasFloat(client, directory, sessionAddress, owner, also) {
26
26
  // Another process (the session's own signer, say) may be sweeping at the same moment; a
27
27
  // rejection for a balance that moved under us is answered by looking again.
28
28
  for (let attempt = 0;; attempt++) {
29
29
  try {
30
- return await sweepOnce(client, directory, sessionAddress, owner);
30
+ return await sweepOnce(client, directory, sessionAddress, owner, also);
31
31
  }
32
32
  catch (error) {
33
33
  if (attempt > 0 || !/[Ii]nsufficient/.test(error.message))
@@ -36,26 +36,32 @@ export async function returnGasFloat(client, directory, sessionAddress, owner) {
36
36
  }
37
37
  }
38
38
  }
39
- async function sweepOnce(client, directory, sessionAddress, owner) {
39
+ /**
40
+ * With `also`, that call rides in the same transaction and the transaction always runs, even
41
+ * for a float too small to be worth sending: the agent's resignation returns its gas as it goes.
42
+ */
43
+ async function sweepOnce(client, directory, sessionAddress, owner, also) {
40
44
  const { balance } = await client.getBalance({ owner: sessionAddress, coinType: SUI });
41
45
  const float = BigInt(balance.addressBalance);
42
- if (float <= DUST)
46
+ if (float <= DUST && !also)
43
47
  return null;
44
48
  const build = (amount, budget) => {
45
49
  const tx = new Transaction();
46
50
  tx.setSender(sessionAddress);
47
51
  tx.setGasPayment([]);
48
52
  tx.setGasBudget(Number(budget));
49
- tx.moveCall({
50
- target: '0x2::balance::send_funds',
51
- typeArguments: [SUI],
52
- arguments: [tx.balance({ balance: amount.toString() }), tx.pure.address(owner)],
53
- });
53
+ also?.(tx);
54
+ if (amount > 0n)
55
+ tx.moveCall({
56
+ target: '0x2::balance::send_funds',
57
+ typeArguments: [SUI],
58
+ arguments: [tx.balance({ balance: amount.toString() }), tx.pure.address(owner)],
59
+ });
54
60
  return tx;
55
61
  };
56
62
  const probeBudget = MIN_BUDGET;
57
63
  const sim = await client.simulateTransaction({
58
- transaction: build(float - probeBudget, probeBudget),
64
+ transaction: build(float > probeBudget ? float - probeBudget : 0n, probeBudget),
59
65
  include: { effects: true },
60
66
  });
61
67
  const t = sim.$kind === 'Transaction' ? sim.Transaction : sim.FailedTransaction;
@@ -66,9 +72,9 @@ async function sweepOnce(client, directory, sessionAddress, owner) {
66
72
  BigInt(used?.storageCost ?? '0') -
67
73
  BigInt(used?.storageRebate ?? '0');
68
74
  const budget = fee * 2n > MIN_BUDGET ? fee * 2n : MIN_BUDGET;
69
- if (float <= budget)
75
+ if (float <= budget && !also)
70
76
  return null;
71
- const amount = float - budget;
77
+ const amount = float > budget ? float - budget : 0n;
72
78
  const bytes = await build(amount, budget).build({ client });
73
79
  await SessionStore.recordSigned(directory, await Transaction.from(bytes).getDigest());
74
80
  const result = await client.signAndExecuteTransaction({
package/dist/plugin.js CHANGED
@@ -21,7 +21,7 @@ import { Transaction } from '@mysten/sui/transactions';
21
21
  import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
22
22
  import { z } from 'zod';
23
23
  import { adoptAuthorization, applyPendingChange, RulesMismatch } from './activation.js';
24
- import { buildResignation, clientFor, deepbookSizes, findPools, quoteSwap, readAllHoldings, readHoldings, readStatus, withMarketFacts, } from './chain.js';
24
+ import { clientFor, deepbookSizes, findPools, quoteSwap, readAllHoldings, readHoldings, readStatus, resignCall, withMarketFacts, } from './chain.js';
25
25
  import { Deployments } from './deployments.js';
26
26
  import { describePolicy, describeSetup, renderRows } from './describe.js';
27
27
  import { address, coinBySymbol, coinInfo, connects, DAY_MS, defaultGasDaily, display, isStable, limitUnits, MAX_TERM_DAYS, poolsFor, recipientName, requiredSui, sameCoin, SetupSchema, showCoin, SUI, uncovered, units, VenueSchema, } from './domain.js';
@@ -737,7 +737,7 @@ export function createPluginMcp(registry) {
737
737
  }
738
738
  });
739
739
  server.registerTool('resign_pass', {
740
- description: "End this key's authority yourself, with no owner signature: one transaction from the agent key, after which the chain refuses every action under the pass. Use it when the work is done and nothing recurring remains, when the owner says stop, after a keyAlert, or on a mismatch. The pass and its allowances stay on chain, inert, until the owner closes the pass from its page and gets the storage deposit back; tell them so. Irreversible: a new pass needs a new proposal.",
740
+ description: "End this key's authority yourself, with no owner signature: one transaction from the agent key that also returns the key's remaining gas to the owner, after which the chain refuses every action under the pass. Use it when the work is done and nothing recurring remains, when the owner says stop, after a keyAlert, or on a mismatch. The pass and its allowances stay on chain, inert, until the owner closes the pass from its page and gets the storage deposit back; tell them so. Irreversible: a new pass needs a new proposal.",
741
741
  inputSchema: {
742
742
  pass: z
743
743
  .string()
@@ -760,23 +760,15 @@ export function createPluginMcp(registry) {
760
760
  const hit = await findPassByAgent(client, d, sessionAddress);
761
761
  if (!hit)
762
762
  throw new Error('No pass for this key is on chain; nothing to resign from');
763
- const tx = buildResignation(d, hit.id);
764
- tx.setSender(sessionAddress);
765
- const bytes = await tx.build({ client });
766
- await SessionStore.recordSigned(store.directory, await Transaction.from(bytes).getDigest());
767
- const outcome = await client.signAndExecuteTransaction({
768
- transaction: bytes,
769
- signer: await store.key(),
770
- });
771
- if (outcome.$kind !== 'Transaction')
772
- throw new Error(`The chain refused the resignation: ${outcome.FailedTransaction.status.error?.message}`);
773
- await client.waitForTransaction({ result: outcome });
763
+ // The key's remaining gas goes back to the owner in the same transaction.
764
+ const swept = await returnGasFloat(client, store.directory, sessionAddress, hit.owner, (tx) => resignCall(tx, d, hit.id));
774
765
  return result({
775
766
  pass: session.id,
776
767
  passId: hit.id,
777
- digest: outcome.Transaction.digest,
768
+ digest: swept.digest,
769
+ gasReturned: swept.amount,
778
770
  status: 'revoked',
779
- next: 'The key can no longer act. Tell the owner the pass is stopped and that closing it from its page refunds the storage deposit; then call forget_pass once it is closed.',
771
+ next: 'The key can no longer act and its gas is back with the owner. Tell them the pass is stopped and that closing it from its page refunds the storage deposit; forget_pass then deletes this session.',
780
772
  });
781
773
  }
782
774
  catch (error) {
package/docs/AGENT.md CHANGED
@@ -51,7 +51,8 @@ pool ids in order, when the pair trades only through other coins, `supply(i, coi
51
51
  `await borrow(i, coin, amount)`, `await repay(i, coin, amount)` (the three that check health first
52
52
  refresh NAVI's oracle prices, which on mainnet must be newer than its update interval), `stake(i, amount, validator)` in SUI with
53
53
  `await pickValidator(i)` for the validator, `unstake(i, stakeId)`, `refillGas(i, amount)` and
54
- `resign(i)`, which ends this key's authority for good. Each
54
+ `resign(i)`, which ends this key's authority for good (the `resign_pass` tool does the same and
55
+ returns the key's gas to the owner in the same transaction). Each
55
56
  returns a `Transaction`; `submit` tops up your gas from the gas allowance when your own balance
56
57
  is below 0.01 SUI (by what the allowance can still give, up to 0.05 SUI), builds with a dry run
57
58
  that sizes the gas budget, signs through the signer, executes and waits.
package/docs/PLAYBOOK.md CHANGED
@@ -239,14 +239,21 @@ Until the owner signs, the old rules apply and `session_info` reports `changing`
239
239
 
240
240
  ## 6. End it
241
241
 
242
- When the work is done and nothing recurring remains, or the owner tells you to stop, call
243
- `resign_pass`: one transaction from your own key, no owner signature, after which the chain
244
- refuses every action under the pass. Tell the owner, and that closing the pass from its page
245
- refunds its storage deposit. It is irreversible; a new pass needs a new proposal.
246
-
247
- The owner has two endings of their own, both on the pass page, which `revoke_pass` opens for the
248
- pass the owner names. Without a pass it opens the owner page, which lists all of the owner's passes and ends any
249
- number of them with one signature; use that when several are to go.
242
+ There are two ways a pass ends, and you should know which one you are in.
243
+
244
+ **You end it.** This is the normal ending. When the work is done and nothing recurring remains,
245
+ or the owner tells you to stop, call `resign_pass`: one transaction from your own key, no owner
246
+ signature. It ends your authority on chain (every later action is refused) and returns the key's
247
+ remaining gas to the owner in the same transaction, so nothing of theirs stays with you. Tell the
248
+ owner the pass is stopped and that closing it from its page deletes the allowances and refunds
249
+ the storage deposit; those are their objects, which only their signature can remove. Resigning
250
+ is irreversible; a new pass needs a new proposal. Then call `forget_pass` for the session, which
251
+ deletes the session directory and its key.
252
+
253
+ **The owner ends it.** When something is wrong on their side, the owner stops or closes the
254
+ pass from its page without you. `revoke_pass` opens that page for the pass the owner names;
255
+ without a pass it opens the owner page, which lists all of the owner's passes and ends any
256
+ number of them with one signature.
250
257
 
251
258
  - **Stop the agent now** revokes the key and deletes the allowances, and keeps the pass and its
252
259
  history on chain. It is the instant answer when something is wrong.
@@ -254,7 +261,6 @@ number of them with one signature; use that when several are to go.
254
261
  and deletes the pass, which refunds its storage deposit. A NAVI position that owes nothing is
255
262
  withdrawn into the owner's wallet first, since NAVI's own app cannot operate a pass's position.
256
263
  A position with debt is handed over as it is, and the owner page lists it with its balances.
257
- This is the normal ending when the owner is done.
258
264
 
259
265
  Tell the owner both exist and that closing refunds the storage cost. They connect the wallet that
260
266
  created the pass, pick an ending and sign. Opening the page revokes nothing; only the signed
@@ -263,10 +269,11 @@ transaction does. Then call `session_info` with `wait: 60` until the status is `
263
269
  its own **Reclaim** button: a NAVI position comes back with its account cap (collateral first
264
270
  when it owes nothing), and a stake as an ordinary `StakedSui`.
265
271
 
266
- Once a pass is closed, the signer returns the key's unspent gas to the owner the next time it
267
- runs. Then call `forget_pass` for the session: it refuses while the pass is live, returns any gas
268
- still there, and deletes the session directory with its key. Offer it for every pass
269
- `list_passes` reports as closed or stopped, and for proposals the owner never signed.
272
+ You notice an ending the owner made from `session_info` (status `revoked` or `closed`) or
273
+ `list_passes`. The signer returns the key's unspent gas to the owner by itself the next time it
274
+ runs; `forget_pass` does the same if that has not happened, then deletes the session directory
275
+ with its key. It refuses while the pass is live. Offer it for every pass `list_passes` reports as
276
+ closed or stopped, and for proposals the owner never signed.
270
277
 
271
278
  `list_passes` may also report `unreadable` sessions from an earlier version of this package.
272
279
  Their passes may still be live: tell the owner to stop or close each one from its pass page on
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mysten-incubation/sui-agent-pass",
3
- "version": "0.1.30",
3
+ "version": "0.1.31",
4
4
  "type": "module",
5
5
  "description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
6
6
  "repository": {
@@ -244,14 +244,21 @@ Until the owner signs, the old rules apply and `session_info` reports `changing`
244
244
 
245
245
  ## 6. End it
246
246
 
247
- When the work is done and nothing recurring remains, or the owner tells you to stop, call
248
- `resign_pass`: one transaction from your own key, no owner signature, after which the chain
249
- refuses every action under the pass. Tell the owner, and that closing the pass from its page
250
- refunds its storage deposit. It is irreversible; a new pass needs a new proposal.
251
-
252
- The owner has two endings of their own, both on the pass page, which `revoke_pass` opens for the
253
- pass the owner names. Without a pass it opens the owner page, which lists all of the owner's passes and ends any
254
- number of them with one signature; use that when several are to go.
247
+ There are two ways a pass ends, and you should know which one you are in.
248
+
249
+ **You end it.** This is the normal ending. When the work is done and nothing recurring remains,
250
+ or the owner tells you to stop, call `resign_pass`: one transaction from your own key, no owner
251
+ signature. It ends your authority on chain (every later action is refused) and returns the key's
252
+ remaining gas to the owner in the same transaction, so nothing of theirs stays with you. Tell the
253
+ owner the pass is stopped and that closing it from its page deletes the allowances and refunds
254
+ the storage deposit; those are their objects, which only their signature can remove. Resigning
255
+ is irreversible; a new pass needs a new proposal. Then call `forget_pass` for the session, which
256
+ deletes the session directory and its key.
257
+
258
+ **The owner ends it.** When something is wrong on their side, the owner stops or closes the
259
+ pass from its page without you. `revoke_pass` opens that page for the pass the owner names;
260
+ without a pass it opens the owner page, which lists all of the owner's passes and ends any
261
+ number of them with one signature.
255
262
 
256
263
  - **Stop the agent now** revokes the key and deletes the allowances, and keeps the pass and its
257
264
  history on chain. It is the instant answer when something is wrong.
@@ -259,7 +266,6 @@ number of them with one signature; use that when several are to go.
259
266
  and deletes the pass, which refunds its storage deposit. A NAVI position that owes nothing is
260
267
  withdrawn into the owner's wallet first, since NAVI's own app cannot operate a pass's position.
261
268
  A position with debt is handed over as it is, and the owner page lists it with its balances.
262
- This is the normal ending when the owner is done.
263
269
 
264
270
  Tell the owner both exist and that closing refunds the storage cost. They connect the wallet that
265
271
  created the pass, pick an ending and sign. Opening the page revokes nothing; only the signed
@@ -268,10 +274,11 @@ transaction does. Then call `session_info` with `wait: 60` until the status is `
268
274
  its own **Reclaim** button: a NAVI position comes back with its account cap (collateral first
269
275
  when it owes nothing), and a stake as an ordinary `StakedSui`.
270
276
 
271
- Once a pass is closed, the signer returns the key's unspent gas to the owner the next time it
272
- runs. Then call `forget_pass` for the session: it refuses while the pass is live, returns any gas
273
- still there, and deletes the session directory with its key. Offer it for every pass
274
- `list_passes` reports as closed or stopped, and for proposals the owner never signed.
277
+ You notice an ending the owner made from `session_info` (status `revoked` or `closed`) or
278
+ `list_passes`. The signer returns the key's unspent gas to the owner by itself the next time it
279
+ runs; `forget_pass` does the same if that has not happened, then deletes the session directory
280
+ with its key. It refuses while the pass is live. Offer it for every pass `list_passes` reports as
281
+ closed or stopped, and for proposals the owner never signed.
275
282
 
276
283
  `list_passes` may also report `unreadable` sessions from an earlier version of this package.
277
284
  Their passes may still be live: tell the owner to stop or close each one from its pass page on