@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 +4 -2
- package/dist/chain.js +2 -4
- package/dist/float.js +18 -12
- package/dist/plugin.js +10 -16
- package/docs/AGENT.md +2 -1
- package/docs/PLAYBOOK.md +22 -13
- package/package.json +1 -1
- package/skills/agent-pass/SKILL.md +22 -13
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,
|
|
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
|
-
|
|
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
|
|
157
|
-
export function
|
|
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
|
-
|
|
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
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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 {
|
|
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
|
-
|
|
764
|
-
|
|
765
|
-
const
|
|
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:
|
|
769
|
+
digest: swept.digest,
|
|
770
|
+
gasReturned: swept.amount,
|
|
778
771
|
status: 'revoked',
|
|
779
|
-
|
|
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
|
|
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
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
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
|
@@ -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
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
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
|