@mysten-incubation/sui-agent-pass 0.1.26 → 0.1.28
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/deployments/mainnet.json +1 -0
- package/deployments/testnet.json +1 -0
- package/dist/activation.js +14 -5
- package/dist/agent.js +74 -6
- package/dist/domain.js +115 -5
- package/dist/explorer.js +68 -26
- package/dist/mcp.js +4 -4
- package/dist/plugin.js +20 -8
- package/dist/server.js +4 -7
- package/docs/PLAYBOOK.md +19 -4
- package/package.json +1 -1
- package/skills/agent-pass/SKILL.md +19 -4
- package/web-dist/agent-setup.md +69 -0
- package/web-dist/assets/index-CiuC-y47.js +846 -0
- package/web-dist/assets/index-Coq1FGKP.css +1 -0
- package/web-dist/assets/{mount-Cf1pxccE.js → mount-CvSnQ6dg.js} +1 -1
- package/web-dist/deployments/mainnet.json +1 -0
- package/web-dist/deployments/testnet.json +1 -0
- package/web-dist/index.html +2 -2
- package/web-dist/assets/index-BP_XyvSE.js +0 -846
- package/web-dist/assets/index-Dtb3YCq1.css +0 -1
|
@@ -126,12 +126,18 @@ Call `propose_authorization` with the rules. It returns `rules`, the exact text
|
|
|
126
126
|
shows, plus `reviewUrl` and `sessionAddress`, and opens the page in the browser. Paste `rules` to
|
|
127
127
|
the owner word for word and never restate the amounts yourself. Tell them to connect their wallet,
|
|
128
128
|
check the page against that text and sign once. The page shows what their wallet holds against
|
|
129
|
-
what the pass needs. If the browser did not open, give them `reviewUrl`.
|
|
129
|
+
what the pass needs. If the browser did not open, give them `reviewUrl`. Hand the link over by
|
|
130
|
+
code, from the tool result into the message, never retyped: it is signed by the session key, and
|
|
131
|
+
the page refuses a link that differs by one character.
|
|
130
132
|
|
|
131
133
|
Then call `session_info` with the pass and `wait: 120`, again while the status is
|
|
132
134
|
`awaiting_authorization`. At `active` the signer has read the pass, the allowances and the
|
|
133
135
|
policies back from chain and checked them against the proposal. Report the pass id, the
|
|
134
|
-
authorization digest, the owner's balances and what the key may still withdraw.
|
|
136
|
+
authorization digest, the owner's balances and what the key may still withdraw. A status of
|
|
137
|
+
`mismatch` means the owner signed something other than the reviewed rules: quote
|
|
138
|
+
`authorizationError`, do not act, and ask the owner to close the pass from its page before you
|
|
139
|
+
propose again. A `chainError` means the signer could not read the chain; the status is unknown
|
|
140
|
+
until a read succeeds, so fix the connection and call again.
|
|
135
141
|
|
|
136
142
|
## 3. Act within the rules
|
|
137
143
|
|
|
@@ -193,6 +199,15 @@ owner's price limit on what went in against what came out.
|
|
|
193
199
|
**Repayments.** Size a repayment from the live debt: an over-payment returns to the owner but
|
|
194
200
|
still counts against the allowance.
|
|
195
201
|
|
|
202
|
+
**One-shot and scheduled runs.** Each run can be one script: `Agent.open(directory)` starts the
|
|
203
|
+
session's signer when none is running and `agent.close()` stops it, so a scheduled job (a daily
|
|
204
|
+
sale on a cron) or a client that starts the MCP server for each call needs nothing kept alive in
|
|
205
|
+
between. Always call `agent.close()`. On a machine behind a proxy, the script needs
|
|
206
|
+
`HTTPS_PROXY` in its environment like the server does. If you run in a hosted VM that can be
|
|
207
|
+
replaced, check before each scheduled run that agent-pass is installed and the session directory
|
|
208
|
+
still exists. If the session directory is gone, the key is lost: tell the owner to close the pass
|
|
209
|
+
from its page and propose a new one.
|
|
210
|
+
|
|
196
211
|
**Outcomes.** `submit` signs through this server, executes on Sui and returns what the chain
|
|
197
212
|
recorded. `success: true` means done. `success: false` means the chain executed the transaction
|
|
198
213
|
and refused it; `reason` is the owner's rule that stopped it, and you quote it. A thrown error
|
|
@@ -208,8 +223,8 @@ allowance has its own cap and 24-hour limit and never touches the asset caps.
|
|
|
208
223
|
## 4. Report the state
|
|
209
224
|
|
|
210
225
|
Call `list_passes`, then `session_info` for each pass the owner asks about (all of them when
|
|
211
|
-
unclear). Report the status (`awaiting_authorization`, `
|
|
212
|
-
or `closed`), the owner's address balances, what the key may still withdraw, its gas, any NAVI
|
|
226
|
+
unclear). Report the status (`awaiting_authorization`, `mismatch`, `active`, `changing`,
|
|
227
|
+
`expired`, `revoked` or `closed`), the owner's address balances, what the key may still withdraw, its gas, any NAVI
|
|
213
228
|
position or stakes in the pass, and for each policy its limit and today's usage
|
|
214
229
|
(`control.policies[*].usage.usedToday`). Quote the `rules` text as returned; do not recompute
|
|
215
230
|
amounts.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Set up Sui Agent Pass
|
|
2
|
+
|
|
3
|
+
You are setting up Sui Agent Pass for the person you work for. It lets you act on their Sui assets
|
|
4
|
+
within rules they sign once in their own wallet. Their coins stay in their wallet, you work with a
|
|
5
|
+
key of your own, and the chain refuses anything outside the rules.
|
|
6
|
+
|
|
7
|
+
Do the steps below, then ask them what they want to do. Do not propose a pass or make any
|
|
8
|
+
transaction during setup.
|
|
9
|
+
|
|
10
|
+
1. **Install** the package (Node 22 or newer):
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install -g @mysten-incubation/sui-agent-pass
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
If you are a coding agent in a terminal on the person's own machine (Claude Code, Codex,
|
|
17
|
+
Hermes, OpenClaw), run `agent-pass connect --client <claude-code|codex|hermes|openclaw>`
|
|
18
|
+
instead of the next step: it registers the server and the playbook with your client. Ask the
|
|
19
|
+
person to restart you, then continue at step 3. Agents in a hosted app or in their own VM or
|
|
20
|
+
sandbox take step 2.
|
|
21
|
+
|
|
22
|
+
Reinstalling or upgrading never touches existing passes or keys.
|
|
23
|
+
|
|
24
|
+
2. **Connect to its MCP server.** If your app lets you add an MCP server, add a stdio server with
|
|
25
|
+
the command `agent-pass mcp`. Otherwise write a small client with the official MCP SDK
|
|
26
|
+
(`@modelcontextprotocol/sdk`) that starts `agent-pass mcp` over stdio, calls its tools and
|
|
27
|
+
reads its resources. Two settings matter:
|
|
28
|
+
- Pass your full environment to the server. The SDK's stdio transport forwards only a small
|
|
29
|
+
default set, and on a machine whose only way out is a proxy, the server needs `HTTPS_PROXY`.
|
|
30
|
+
- Give tool calls a timeout of several minutes. `session_info` can wait up to 120 seconds for
|
|
31
|
+
the owner's signature, longer than the SDK's 60-second default.
|
|
32
|
+
|
|
33
|
+
For example (in its own npm project, after `npm install @modelcontextprotocol/sdk`):
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
37
|
+
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
38
|
+
|
|
39
|
+
const client = new Client({ name: 'agent-pass-client', version: '1.0.0' });
|
|
40
|
+
await client.connect(
|
|
41
|
+
new StdioClientTransport({ command: 'agent-pass', args: ['mcp'], env: process.env }),
|
|
42
|
+
);
|
|
43
|
+
const [, , kind, name, args] = process.argv;
|
|
44
|
+
const result =
|
|
45
|
+
kind === 'read'
|
|
46
|
+
? await client.readResource({ uri: name })
|
|
47
|
+
: await client.callTool({ name, arguments: JSON.parse(args ?? '{}') }, undefined, {
|
|
48
|
+
timeout: 300_000,
|
|
49
|
+
});
|
|
50
|
+
console.log(JSON.stringify(result, null, 2));
|
|
51
|
+
await client.close();
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Run it as `node client.mjs call list_passes '{}'` or `node client.mjs read agent-pass://playbook`.
|
|
55
|
+
Keep the client for later conversations, as a saved skill if your app has them.
|
|
56
|
+
|
|
57
|
+
3. **Read the playbook.** Read the resource `agent-pass://playbook` in full and follow it for
|
|
58
|
+
everything you do with Agent Pass. It explains how to turn a request into rules, how the owner
|
|
59
|
+
signs, and how to act and report.
|
|
60
|
+
|
|
61
|
+
4. **Check the connection.** Call `list_passes`. On mainnet, each pool should show a `price`. A
|
|
62
|
+
`priceError` means this machine cannot reach the Sui full node; check the network or proxy and
|
|
63
|
+
tell the person instead of going on.
|
|
64
|
+
|
|
65
|
+
5. **Hand over.** Tell the person setup is done and ask what they want you to do with their Sui
|
|
66
|
+
assets. Ask for their wallet address so you can see what they hold.
|
|
67
|
+
|
|
68
|
+
Never print or copy the agent key or any file under `~/.sui-agent-pass`. If something fails, give
|
|
69
|
+
the person the exact error text and say whether anything executed on chain.
|