@mysten-incubation/sui-agent-pass 0.1.10 → 0.1.12

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/storage.js CHANGED
@@ -2,7 +2,7 @@
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
  /** Disk owns session persistence; it does not decide whether a chain session is valid. */
4
4
  import { randomBytes } from 'node:crypto';
5
- import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
5
+ import { appendFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
6
6
  import { join } from 'node:path';
7
7
  import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
8
8
  import { normalizeSuiAddress } from '@mysten/sui/utils';
@@ -80,6 +80,18 @@ export class SessionStore {
80
80
  throw new Error('session.key must be accessible only to its owner (chmod 600)');
81
81
  return Ed25519Keypair.fromSecretKey((await readFile(path, 'utf8')).trim());
82
82
  }
83
+ /**
84
+ * Notes a digest this machine signed with the session key, before the signature leaves it. The
85
+ * key signs nowhere else, so a transaction from the session address missing here was signed
86
+ * by a copy of the key.
87
+ */
88
+ static async recordSigned(directory, digest) {
89
+ await appendFile(join(directory, 'signed.log'), `${digest}\n`, { mode: 0o600 });
90
+ }
91
+ static async signedDigests(directory) {
92
+ const text = await readFile(join(directory, 'signed.log'), 'utf8').catch(() => '');
93
+ return new Set(text.split('\n').filter(Boolean));
94
+ }
83
95
  /** Deletes a session directory, key included. Callers make sure nothing on chain still needs it. */
84
96
  static async forget(directory) {
85
97
  await rm(directory, { recursive: true, force: true });
package/docs/AGENT.md CHANGED
@@ -167,17 +167,25 @@ window; `0x3::validator_set` 10 below the 1 SUI minimum stake.
167
167
 
168
168
  ## The pass
169
169
 
170
- | Function | Type arguments | Explicit arguments |
171
- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
- | `pass::transfer` | `[coin]` | pass, config, allowance, withdrawal, recipient name, clock |
173
- | `pass::deepbook_base_to_quote` / `deepbook_quote_to_base` | `[base, quote]` | pass, config, allowance, withdrawal, a DeepBook pool from `deployment.pools` (`coinA` is base, `coinB` quote), min_out, clock |
174
- | `pass::cetus_a_to_b` / `cetus_b_to_a` | `[a, b]` | pass, config, allowance, withdrawal, `protocols.cetus.configId`, a Cetus pool from `deployment.pools`, min_out, clock |
175
- | `pass::navi_supply` | `[coin]` | pass, config, allowance, withdrawal, `navi.storageId`, `navi.reserves[coin].poolId`, `navi.reserves[coin].assetId`, `navi.incentiveV2Id`, `navi.incentiveV3Id`, clock |
176
- | `pass::navi_withdraw` / `navi_borrow` | `[coin]` | pass, config, `navi.oracleId`, storage, pool, asset, incentiveV2, incentiveV3, amount, clock |
177
- | `pass::navi_repay` | `[coin]` | pass, config, allowance, withdrawal, oracle, storage, pool, asset, incentiveV2, incentiveV3, clock |
178
- | `pass::stake` | | pass, config, SUI allowance, withdrawal, `0x5`, validator address, clock; returns the stake's ID |
179
- | `pass::unstake` | | pass, config, `0x5`, stake ID, clock |
180
- | `pass::add_policy`, `remove_policy`, `set_agent`, `rotate_allowance`, `revoke_agent`, `deposit_object`, `withdraw_object`, `navi_open`, `destroy` | | **owner sender only**; installs take `config` after the pass, exits do not |
170
+ | Function | Type arguments | Explicit arguments |
171
+ | ---------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
+ | `pass::transfer` | `[coin]` | pass, config, allowance, withdrawal, recipient name, clock |
173
+ | `pass::deepbook_base_to_quote` / `deepbook_quote_to_base` | `[base, quote]` | pass, config, allowance, withdrawal, a DeepBook pool from `deployment.pools` (`coinA` is base, `coinB` quote), min_out, clock |
174
+ | `pass::cetus_a_to_b` / `cetus_b_to_a` | `[a, b]` | pass, config, allowance, withdrawal, `protocols.cetus.configId`, a Cetus pool from `deployment.pools`, min_out, clock |
175
+ | `pass::navi_supply` | `[coin]` | pass, config, allowance, withdrawal, `navi.storageId`, `navi.reserves[coin].poolId`, `navi.reserves[coin].assetId`, `navi.incentiveV2Id`, `navi.incentiveV3Id`, clock |
176
+ | `pass::navi_withdraw` / `navi_borrow` | `[coin]` | pass, config, `navi.oracleId`, storage, pool, asset, incentiveV2, incentiveV3, `0x5`, amount, clock |
177
+ | `pass::navi_repay` | `[coin]` | pass, config, allowance, withdrawal, oracle, storage, pool, asset, incentiveV2, incentiveV3, clock |
178
+ | `pass::stake` | | pass, config, SUI allowance, withdrawal, `0x5`, validator address, clock; returns the stake's ID |
179
+ | `pass::unstake` | | pass, config, `0x5`, stake ID, clock |
180
+ | `pass::add_policy`, `remove_policy`, `set_term`, `revoke_agent`, `deposit_object`, `withdraw_object`, `navi_open`, `destroy` | | **owner sender only**; installs take `config` after the pass, exits do not |
181
+
182
+ A pass's ID is derived from the `Config` and its agent key: `pass::pass_of(config, agent)` on
183
+ chain, `passIdOf(deployment, agent)` in the client. A key has one pass, ever.
184
+
185
+ The agent's actions and the owner's calls on a live pass are `entry` functions: a transaction
186
+ calls them directly, and other packages cannot. The calls that run while a new pass is still
187
+ unshared (`create`, `issue`, `add_policy`, `navi_open`, `deposit_object`), the ones that return
188
+ a value (`remove_policy`, `withdraw_object`) and the getters are `public`.
181
189
 
182
190
  The allowance for a spend is `active.allowances[coin].allowance`, one per coin the rules
183
191
  spend; the withdrawal's `type` is the coin, `from` is `"allowance"` and `funder` is
package/docs/PLAYBOOK.md CHANGED
@@ -78,9 +78,11 @@ the allowance back. A supply-and-withdraw or stake-and-unstake cycle costs the a
78
78
  size lending and staking limits for the cycles the agent will run, and tell the owner when they
79
79
  ask for something like "restake with a better validator".
80
80
 
81
- **Term and gas.** `days` is the agent's term, 1 to 30. `gasSui` (default 0.05) is a stipend sent
81
+ **Term and gas.** `days` is the agent's term, from 1 up to the network's `maxTermDays` in
82
+ `list_passes`. `gasSui` (default 0.05) is a stipend sent
82
83
  to the agent key, outside the rules. `gasCapSui` (default 0.1) is a separate allowance the key
83
- draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its daily limit.
84
+ draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its limit per 24
85
+ hours from the first top-up. Call it that, not a limit per UTC day like the asset limits.
84
86
 
85
87
  **What the owner needs.** Signing moves only the agent's gas stipend and pays the fee, so that is
86
88
  all the owner must hold, in SUI. The caps are limits on what the rules may draw later, not money
@@ -131,6 +133,11 @@ Start with `session_info`. It returns:
131
133
  - `directory`, `sdk` and `server`: the session directory, how to install and import the SDK,
132
134
  and this server's version (after an upgrade the client must restart the server).
133
135
 
136
+ **Key alert.** When `list_passes` or `session_info` carries `keyAlert`, the chain shows
137
+ transactions from the agent key that this machine never signed: a copy of the key is in use
138
+ elsewhere. Stop acting, tell the owner at once with the digests, and offer `revoke_pass` so they
139
+ can stop the agent from the pass page.
140
+
134
141
  **Updates.** When `server.update` is present in `list_passes` or `session_info`, a newer release
135
142
  is out. Tell the owner once per conversation, with `server.update.command` and the reminder to
136
143
  restart the agent afterwards, then carry on with the task; never run the command yourself.
@@ -178,7 +185,7 @@ enforcement. `submit` tops up your gas from the gas allowance when it runs low.
178
185
  `@mysten/sui` following the guide, sign it with `sign_transaction` and execute it yourself. Every
179
186
  spend takes the allowance object and a withdrawal input right after the pass. On this path gas is
180
187
  yours: when the key holds under 0.01 SUI, draw on the gas allowance as the guide shows. That
181
- allowance has its own cap and daily limit and never touches the asset caps.
188
+ allowance has its own cap and 24-hour limit and never touches the asset caps.
182
189
 
183
190
  ## 4. Report the state
184
191
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mysten-incubation/sui-agent-pass",
3
- "version": "0.1.10",
3
+ "version": "0.1.12",
4
4
  "type": "module",
5
5
  "description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
6
6
  "repository": {
@@ -65,7 +65,7 @@
65
65
  },
66
66
  "dependencies": {
67
67
  "@inquirer/prompts": "7.10.1",
68
- "@modelcontextprotocol/sdk": "1.30.1",
68
+ "@modelcontextprotocol/sdk": "1.32.1",
69
69
  "@mysten-incubation/dev-wallet": "0.5.1",
70
70
  "@mysten/dapp-kit-core": "1.6.33",
71
71
  "@mysten/dapp-kit-react": "2.1.35",
@@ -89,7 +89,7 @@
89
89
  "prettier": "3.6.2",
90
90
  "tsx": "4.23.15",
91
91
  "typescript": "5.9.2",
92
- "vite": "7.3.6"
92
+ "vite": "7.3.7"
93
93
  },
94
94
  "overrides": {
95
95
  "axios": ">=1.18.0"
@@ -83,9 +83,11 @@ the allowance back. A supply-and-withdraw or stake-and-unstake cycle costs the a
83
83
  size lending and staking limits for the cycles the agent will run, and tell the owner when they
84
84
  ask for something like "restake with a better validator".
85
85
 
86
- **Term and gas.** `days` is the agent's term, 1 to 30. `gasSui` (default 0.05) is a stipend sent
86
+ **Term and gas.** `days` is the agent's term, from 1 up to the network's `maxTermDays` in
87
+ `list_passes`. `gasSui` (default 0.05) is a stipend sent
87
88
  to the agent key, outside the rules. `gasCapSui` (default 0.1) is a separate allowance the key
88
- draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its daily limit.
89
+ draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its limit per 24
90
+ hours from the first top-up. Call it that, not a limit per UTC day like the asset limits.
89
91
 
90
92
  **What the owner needs.** Signing moves only the agent's gas stipend and pays the fee, so that is
91
93
  all the owner must hold, in SUI. The caps are limits on what the rules may draw later, not money
@@ -136,6 +138,11 @@ Start with `session_info`. It returns:
136
138
  - `directory`, `sdk` and `server`: the session directory, how to install and import the SDK,
137
139
  and this server's version (after an upgrade the client must restart the server).
138
140
 
141
+ **Key alert.** When `list_passes` or `session_info` carries `keyAlert`, the chain shows
142
+ transactions from the agent key that this machine never signed: a copy of the key is in use
143
+ elsewhere. Stop acting, tell the owner at once with the digests, and offer `revoke_pass` so they
144
+ can stop the agent from the pass page.
145
+
139
146
  **Updates.** When `server.update` is present in `list_passes` or `session_info`, a newer release
140
147
  is out. Tell the owner once per conversation, with `server.update.command` and the reminder to
141
148
  restart the agent afterwards, then carry on with the task; never run the command yourself.
@@ -183,7 +190,7 @@ enforcement. `submit` tops up your gas from the gas allowance when it runs low.
183
190
  `@mysten/sui` following the guide, sign it with `sign_transaction` and execute it yourself. Every
184
191
  spend takes the allowance object and a withdrawal input right after the pass. On this path gas is
185
192
  yours: when the key holds under 0.01 SUI, draw on the gas allowance as the guide shows. That
186
- allowance has its own cap and daily limit and never touches the asset caps.
193
+ allowance has its own cap and 24-hour limit and never touches the asset caps.
187
194
 
188
195
  ## 4. Report the state
189
196