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

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,14 +21,14 @@ 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';
28
28
  import { findPassByAgent, passIdOf } from './explorer.js';
29
29
  import { passEnded, returnGasFloat } from './float.js';
30
30
  import { failure, INSTRUCTIONS, keyAlert, MAX_TOOL_INPUT_ELEMENTS, registerDocs, result, serverInfo, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
31
- import { authenticated, body, ownerPageUrl, startServer } from './server.js';
31
+ import { authenticated, body, ownerPageUrl, passPageUrl, startServer } from './server.js';
32
32
  import { SessionSigner } from './signer.js';
33
33
  import { SessionStore, token } from './storage.js';
34
34
  export const defaultRoot = () => join(homedir(), '.sui-agent-pass');
@@ -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,17 @@ 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));
765
+ const { origin } = await registry.server(session);
774
766
  return result({
775
767
  pass: session.id,
776
768
  passId: hit.id,
777
- digest: outcome.Transaction.digest,
769
+ digest: swept.digest,
770
+ gasReturned: swept.amount,
778
771
  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.',
772
+ passUrl: passPageUrl(d, origin, hit.id),
773
+ next: 'The key can no longer act under the rules and its gas is back with the owner. Send them passUrl and ask them to close the pass there when convenient: that deletes the allowances, including the gas allowance this key could still draw on up to its cap, and refunds the storage deposit. Then call forget_pass to delete this session.',
780
774
  });
781
775
  }
782
776
  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,23 @@ 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. It
248
+ returns `passUrl`: send it to the owner and ask them to close the pass there when convenient.
249
+ That deletes the allowances and refunds the storage deposit, and it matters beyond tidiness: the
250
+ gas allowance has no policy, so until it is deleted the key could still draw on it up to its
251
+ cap. Those are the owner's objects, which only their signature can remove. Resigning is
252
+ irreversible; a new pass needs a new proposal. Then call `forget_pass` for the session, which
253
+ deletes the session directory and its key.
254
+
255
+ **The owner ends it.** When something is wrong on their side, the owner stops or closes the
256
+ pass from its page without you. `revoke_pass` opens that page for the pass the owner names;
257
+ without a pass it opens the owner page, which lists all of the owner's passes and ends any
258
+ number of them with one signature.
250
259
 
251
260
  - **Stop the agent now** revokes the key and deletes the allowances, and keeps the pass and its
252
261
  history on chain. It is the instant answer when something is wrong.
@@ -254,7 +263,6 @@ number of them with one signature; use that when several are to go.
254
263
  and deletes the pass, which refunds its storage deposit. A NAVI position that owes nothing is
255
264
  withdrawn into the owner's wallet first, since NAVI's own app cannot operate a pass's position.
256
265
  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
266
 
259
267
  Tell the owner both exist and that closing refunds the storage cost. They connect the wallet that
260
268
  created the pass, pick an ending and sign. Opening the page revokes nothing; only the signed
@@ -263,10 +271,11 @@ transaction does. Then call `session_info` with `wait: 60` until the status is `
263
271
  its own **Reclaim** button: a NAVI position comes back with its account cap (collateral first
264
272
  when it owes nothing), and a stake as an ordinary `StakedSui`.
265
273
 
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.
274
+ You notice an ending the owner made from `session_info` (status `revoked` or `closed`) or
275
+ `list_passes`. The signer returns the key's unspent gas to the owner by itself the next time it
276
+ runs; `forget_pass` does the same if that has not happened, then deletes the session directory
277
+ with its key. It refuses while the pass is live. Offer it for every pass `list_passes` reports as
278
+ closed or stopped, and for proposals the owner never signed.
270
279
 
271
280
  `list_passes` may also report `unreadable` sessions from an earlier version of this package.
272
281
  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.32",
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,23 @@ 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. It
253
+ returns `passUrl`: send it to the owner and ask them to close the pass there when convenient.
254
+ That deletes the allowances and refunds the storage deposit, and it matters beyond tidiness: the
255
+ gas allowance has no policy, so until it is deleted the key could still draw on it up to its
256
+ cap. Those are the owner's objects, which only their signature can remove. Resigning is
257
+ irreversible; a new pass needs a new proposal. Then call `forget_pass` for the session, which
258
+ deletes the session directory and its key.
259
+
260
+ **The owner ends it.** When something is wrong on their side, the owner stops or closes the
261
+ pass from its page without you. `revoke_pass` opens that page for the pass the owner names;
262
+ without a pass it opens the owner page, which lists all of the owner's passes and ends any
263
+ number of them with one signature.
255
264
 
256
265
  - **Stop the agent now** revokes the key and deletes the allowances, and keeps the pass and its
257
266
  history on chain. It is the instant answer when something is wrong.
@@ -259,7 +268,6 @@ number of them with one signature; use that when several are to go.
259
268
  and deletes the pass, which refunds its storage deposit. A NAVI position that owes nothing is
260
269
  withdrawn into the owner's wallet first, since NAVI's own app cannot operate a pass's position.
261
270
  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
271
 
264
272
  Tell the owner both exist and that closing refunds the storage cost. They connect the wallet that
265
273
  created the pass, pick an ending and sign. Opening the page revokes nothing; only the signed
@@ -268,10 +276,11 @@ transaction does. Then call `session_info` with `wait: 60` until the status is `
268
276
  its own **Reclaim** button: a NAVI position comes back with its account cap (collateral first
269
277
  when it owes nothing), and a stake as an ordinary `StakedSui`.
270
278
 
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.
279
+ You notice an ending the owner made from `session_info` (status `revoked` or `closed`) or
280
+ `list_passes`. The signer returns the key's unspent gas to the owner by itself the next time it
281
+ runs; `forget_pass` does the same if that has not happened, then deletes the session directory
282
+ with its key. It refuses while the pass is live. Offer it for every pass `list_passes` reports as
283
+ closed or stopped, and for proposals the owner never signed.
275
284
 
276
285
  `list_passes` may also report `unreadable` sessions from an earlier version of this package.
277
286
  Their passes may still be live: tell the owner to stop or close each one from its pass page on