@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.
@@ -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`, `active`, `changing`, `expired`, `revoked`
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.