@mysten-incubation/sui-agent-pass 0.1.16 → 0.1.18

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/README.md CHANGED
@@ -169,7 +169,8 @@ and MCP signing. For the wallet connection/signature flow use the flow below.
169
169
 
170
170
  Use a deployed configuration, or `npm run devnet -- --owner <address>`, which publishes to
171
171
  devnet with a faucet-funded publisher, funds your wallet address from the faucet and writes the
172
- deployment to `~/.sui-agent-pass/deployment.json` for the Claude Code plugin. Slush offers
172
+ deployment to `.local/devnet/deployment.json`. Tell the agent to pass that file's absolute path
173
+ as `deployment` when proposing a pass. Slush offers
173
174
  mainnet, testnet and devnet only. `npm run demo -- --wallet` keeps a localnet alive and prints a
174
175
  funded throwaway owner key for a wallet that accepts a custom RPC URL; not verified with any.
175
176
 
@@ -181,7 +182,7 @@ npm run deploy -- create --directory .local/testnet
181
182
  # Fund it with at least 11 test SUI, then:
182
183
  npm run deploy -- resume --directory .local/testnet
183
184
 
184
- # A private deployment.json replaces the bundled network for new passes:
185
+ # Select a private deployment explicitly for each new pass:
185
186
  node dist/cli.js connect # then ask the agent; it passes deployment: .local/testnet/deployment.json
186
187
  # devnet works the same way:
187
188
  npm run deploy -- create --network devnet --directory .local/devnet
@@ -202,8 +203,9 @@ account when lending is allowed, and sends SUI to the session's **address balanc
202
203
  service re-reads everything that landed on chain and compares it with what you reviewed before
203
204
  the signer serves the key.
204
205
 
205
- Register the agents that may use your passes once with `connect` (it asks which ones it finds on
206
- the machine). Then start Claude anywhere:
206
+ Register the agents that may use your passes once with `connect`. Its main menu lists detected
207
+ agents; **Other / manual setup** offers undetected clients and a generic MCP configuration.
208
+ You can also select a client directly with `--client <name>`. Then start Claude anywhere:
207
209
 
208
210
  ```sh
209
211
  claude
@@ -238,12 +240,12 @@ terminal.
238
240
  cd ~/github/sui-agent-vault
239
241
  npm ci && npm run toolchain && npm run build
240
242
  # Publish with a faucet-funded key, fund your Slush address from the faucet, and write
241
- # ~/.sui-agent-pass/deployment.json:
243
+ # .local/devnet/deployment.json (the command prints its absolute path):
242
244
  npm run devnet -- --owner <your Slush address>
243
245
  cd ~/anywhere && claude --plugin-dir ~/github/sui-agent-vault/plugin
244
246
  ```
245
247
 
246
- Then, in Claude Code:
248
+ Then tell Claude Code to use the printed deployment path for this rehearsal, and ask:
247
249
 
248
250
  > Manage 1 SUI and 100 USDC for me. Sell at most 0.1 SUI a day on DeepBook, never below
249
251
  > 1.8 USDC. You may pay alice (0x…) up to 10 USDC a time and 20 a day. One week.
@@ -258,8 +260,18 @@ guidance Claude follows is [`docs/PLAYBOOK.md`](docs/PLAYBOOK.md), which the MCP
258
260
  client as the `agent-pass://playbook` resource; the plugin skills only point at it.
259
261
 
260
262
  The MCP is `node dist/cli.js mcp`. It keeps sessions under `~/.sui-agent-pass/sessions/` and
261
- reads `deployment.json` from that directory; Claude can also pass another deployment path to
262
- `propose_authorization`. The plugin and Claude Code run as the same OS user: the session key
263
+ uses the deployments bundled with npm. Custom deployments require an explicit `deployment`
264
+ path on `propose_authorization`, or `agent-pass mcp --deployment /absolute/path/deployment.json`.
265
+ For development, use `--root /absolute/path/development-sessions` to keep sessions separate.
266
+ If a network and custom file are both selected, their networks must match.
267
+
268
+ An old `~/.sui-agent-pass/deployment.json` is no longer loaded automatically. If one remains,
269
+ `list_passes` reports a migration message, and proposals without an explicit network or custom
270
+ deployment stop rather than silently choosing another network. Archive the old file if it is
271
+ obsolete, or select it explicitly if it is still needed. Existing sessions keep their own
272
+ deployment; upgrades can refresh addresses only within the same network and original package.
273
+
274
+ The plugin and Claude Code run as the same OS user: the session key
263
275
  is not hidden from Claude by the operating system, and the on-chain rules are the boundary.
264
276
 
265
277
  ## The site
@@ -7,7 +7,11 @@ One `deployment.json` per public network, committed here and shipped in the npm
7
7
  `files` field in `package.json`). Each records the published package and object IDs, the gRPC URL
8
8
  and the chain identifier for that network. The stdio server loads one of these when
9
9
  the agent names a `network` in `propose_authorization`, so an installed client needs no local
10
- publish; a private `deployment.json` under `~/.sui-agent-pass` or a `deployment` path overrides.
10
+ publish. A custom deployment requires an explicit tool `deployment` path or server
11
+ `--deployment`; when a network is also supplied, it must match the file. A legacy
12
+ `~/.sui-agent-pass/deployment.json` is never loaded automatically: it triggers a migration
13
+ message and blocks proposals without an explicit selection until the owner chooses a network
14
+ or custom file, or archives the obsolete file. Existing sessions keep their deployment.
11
15
 
12
16
  `mainnet.json` is the mainnet test copy of the package (`0x389b5817…063f`, published
13
17
  2026-10-28 from the code that will launch, caps with its publisher), for dogfooding with small
@@ -17,8 +21,8 @@ the hosted site. `testnet.json` is the same code, published to testnet on 2026-1
17
21
  stand-ins with 2 SUI of depth, so dogfooders get transfers and staking there and trade on
18
22
  mainnet. The stand-in pools stay on chain, and the previous revision of this file in git keeps
19
23
  their ids; the tests publish their own stand-ins. Any Move change means a new publish and a new
20
- file here. `npm run devnet` publishes to devnet and writes its
21
- `deployment.json` for the plugin; `npm run deploy -- create --network <name>` publishes to
24
+ file here. `npm run devnet` publishes to devnet and writes its project-local
25
+ `deployment.json` for explicit selection; `npm run deploy -- create --network <name>` publishes to
22
26
  testnet or devnet. At launch, commit the resulting `deployment.json` here as `<name>.json`.
23
27
 
24
28
  The site build (`npm run build`) copies these files into `web-dist/deployments/`, so the hosted
package/dist/cli.js CHANGED
@@ -14,30 +14,6 @@ import { cliInvocation, defaultRoot, forgetSession, openBrowser, servePlugin, se
14
14
  import { startServer } from './server.js';
15
15
  import { SessionStore } from './storage.js';
16
16
  const quote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
17
- /**
18
- * Picks several things one at a time with arrows and enter, the way a single-choice menu
19
- * works, instead of a checkbox whose space key many people never find. Each pick leaves the
20
- * list; the last entry ends the picking. `atLeastOne` refuses to end with nothing picked.
21
- */
22
- async function pickMany(message, choices, done, atLeastOne) {
23
- const picked = [];
24
- let left = [...choices];
25
- while (left.length) {
26
- const pick = await select({
27
- message: picked.length ? `${message} (${picked.length} picked so far)` : message,
28
- choices: [...left, { name: done, value: null }],
29
- });
30
- if (pick === null) {
31
- if (picked.length || !atLeastOne)
32
- break;
33
- console.log('Pick at least one.');
34
- continue;
35
- }
36
- picked.push(pick);
37
- left = left.filter((c) => c.value !== pick);
38
- }
39
- return picked;
40
- }
41
17
  export async function serve(store, port = 0, open = true) {
42
18
  const server = await startServer(store, port);
43
19
  console.log(`\nOwner page: ${server.ownerUrl}\nSession address: ${store.state.sessionAddress}\nSession directory: ${store.directory}`);
@@ -85,8 +61,8 @@ program
85
61
  program
86
62
  .command('mcp')
87
63
  .description('Stdio MCP for the Claude Code plugin: propose, watch, sign for and revoke passes')
88
- .option('--root <directory>', 'Sessions and default deployment', defaultRoot())
89
- .option('--deployment <path>', 'deployment.json used for new passes')
64
+ .option('--root <directory>', 'Session storage directory', defaultRoot())
65
+ .option('--deployment <path>', 'Explicit custom deployment for development; otherwise use bundled networks')
90
66
  .option('--no-open', 'Do not open the browser for owner pages')
91
67
  .option('--http <port>', 'Serve on a local HTTP endpoint instead of stdio; writes url and bearer token to <root>/mcp-http.json')
92
68
  .action(async (o) => {
@@ -256,14 +232,14 @@ async function installSkill(client) {
256
232
  await symlink(source, target, 'dir');
257
233
  console.log(`${temporary ? 'Copied' : 'Linked'} the agent-pass skill into ${target}.`);
258
234
  }
259
- /** The agents on this machine, as far as their usual files show; nothing is preselected. */
235
+ /** Detected agents first; other clients remain available through a separate manual menu. */
260
236
  async function chooseClients() {
261
237
  const home = homedir();
262
- const found = async (path) => access(path).then(() => ' (found)', () => '');
238
+ const found = async (path) => access(path).then(() => true, () => false);
263
239
  const onPath = (bin) => new Promise((done) => {
264
240
  const child = spawn('sh', ['-c', `command -v ${bin}`], { stdio: 'ignore' });
265
- child.once('error', () => done(''));
266
- child.once('exit', (code) => done(code === 0 ? ' (found)' : ''));
241
+ child.once('error', () => done(false));
242
+ child.once('exit', (code) => done(code === 0));
267
243
  });
268
244
  const desktopConfig = process.platform === 'darwin'
269
245
  ? join(home, 'Library/Application Support/Claude')
@@ -277,15 +253,43 @@ async function chooseClients() {
277
253
  found(join(home, '.hermes')),
278
254
  found(join(home, '.codex')),
279
255
  ]);
256
+ const choices = [
257
+ { name: 'Claude Code', value: 'claude-code', found: claude },
258
+ { name: 'Claude Desktop', value: 'claude-desktop', found: desktop },
259
+ { name: 'Cursor', value: 'cursor', found: cursor },
260
+ { name: 'Hermes', value: 'hermes', found: hermes },
261
+ { name: 'Codex', value: 'codex', found: codex },
262
+ { name: 'Generic MCP configuration', value: 'json', found: false },
263
+ ];
264
+ if (!choices.some((c) => c.found))
265
+ console.log('No supported agents detected. Choose Other / manual setup to configure one.');
280
266
  console.log('Pick one at a time with the arrow keys and enter; add more after.');
281
- const picked = await pickMany('Which agent may use your passes?', [
282
- { name: `Claude Code${claude}`, value: 'claude-code' },
283
- { name: `Claude Desktop${desktop}`, value: 'claude-desktop' },
284
- { name: `Cursor${cursor}`, value: 'cursor' },
285
- { name: `Hermes${hermes}`, value: 'hermes' },
286
- { name: `Codex${codex}`, value: 'codex' },
287
- { name: 'Something else (prints a generic MCP entry)', value: 'json' },
288
- ], "That's all", false);
267
+ const picked = [];
268
+ while (picked.length < choices.length) {
269
+ const remaining = choices.filter((c) => !picked.includes(c.value));
270
+ const manual = remaining.filter((c) => !c.found);
271
+ const pick = await select({
272
+ message: `Which agent may use your passes?${picked.length ? ` (${picked.length} picked so far)` : ''}`,
273
+ choices: [
274
+ ...remaining.filter((c) => c.found),
275
+ ...(manual.length ? [{ name: 'Other / manual setup', value: 'manual' }] : []),
276
+ { name: "That's all", value: null },
277
+ ],
278
+ });
279
+ if (pick === null)
280
+ break;
281
+ if (pick === 'manual') {
282
+ const client = await select({
283
+ message: 'Choose a client to configure manually',
284
+ choices: [...manual, { name: 'Back', value: null }],
285
+ });
286
+ if (client !== null)
287
+ picked.push(client);
288
+ }
289
+ else {
290
+ picked.push(pick);
291
+ }
292
+ }
289
293
  if (picked.length === 0) {
290
294
  const finish = await select({
291
295
  message: 'No agent picked. Finish without registering any?',
@@ -0,0 +1,80 @@
1
+ // Copyright (c) Mysten Labs, Inc.
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { lstat, readFile } from 'node:fs/promises';
4
+ import { join, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { normalizeSuiAddress } from '@mysten/sui/utils';
7
+ import { DeploymentSchema } from './domain.js';
8
+ const exists = (path) => lstat(path).then(() => true, (error) => {
9
+ if (error.code === 'ENOENT')
10
+ return false;
11
+ throw error;
12
+ });
13
+ const read = async (path) => DeploymentSchema.parse(JSON.parse(await readFile(path, 'utf8')));
14
+ /** Bundled network records and explicitly selected development deployments. No chain access. */
15
+ export class Deployments {
16
+ root;
17
+ configured;
18
+ constructor(root, configured) {
19
+ this.root = root;
20
+ this.configured = configured;
21
+ }
22
+ path(override) {
23
+ const path = override ?? this.configured;
24
+ return path === undefined ? undefined : resolve(path);
25
+ }
26
+ /** Never parse an old implicit override, even when it is malformed or from an older release. */
27
+ async migrationNotice() {
28
+ const legacy = join(this.root, 'deployment.json');
29
+ if (this.configured !== undefined || !(await exists(legacy)))
30
+ return;
31
+ return `An old deployment override exists at ${legacy}. It is no longer loaded automatically. Before creating a new pass, ask the owner to choose a bundled network explicitly, or select the custom file with deployment (or start MCP with --deployment). Do not choose a different network on their behalf. Archive the old file when it is no longer needed. Existing passes keep their deployment.`;
32
+ }
33
+ bundledPath(network) {
34
+ return fileURLToPath(new URL(`../deployments/${network}.json`, import.meta.url));
35
+ }
36
+ async bundledNetworks() {
37
+ const all = ['mainnet', 'testnet', 'devnet'];
38
+ const present = await Promise.all(all.map((n) => exists(this.bundledPath(n))));
39
+ return all.filter((_, i) => present[i]);
40
+ }
41
+ async bundled(network) {
42
+ return read(this.bundledPath(network));
43
+ }
44
+ /** An explicit file, otherwise a bundled network. Conflicting choices never switch networks. */
45
+ async load(override, network) {
46
+ const path = this.path(override);
47
+ if (path !== undefined) {
48
+ const d = await read(path);
49
+ if (network !== undefined && network !== d.network)
50
+ throw new Error(`Deployment ${path} is for ${d.network}, but ${network} was requested. Select a matching deployment or remove the custom deployment selection to use a bundled network.`);
51
+ return d;
52
+ }
53
+ if (network === undefined) {
54
+ const notice = await this.migrationNotice();
55
+ if (notice)
56
+ throw new Error(notice);
57
+ }
58
+ const bundled = await this.bundledNetworks();
59
+ const chosen = network ?? bundled[0];
60
+ if (!chosen || !bundled.includes(chosen))
61
+ throw new Error(`No bundled deployment for ${network ?? 'any network'}: this package ships ${bundled.join(', ') || 'none'}. For a custom deployment, supply its path explicitly with deployment or --deployment.`);
62
+ return this.bundled(chosen);
63
+ }
64
+ /** Refresh an existing session only within its original network and package. */
65
+ async current(network, packageId) {
66
+ const path = this.path();
67
+ const candidates = [
68
+ ...(path === undefined ? [] : [() => read(path)]),
69
+ () => this.bundled(network),
70
+ ];
71
+ for (const read of candidates) {
72
+ const d = await read().catch(() => null);
73
+ if (d &&
74
+ d.network === network &&
75
+ normalizeSuiAddress(d.packageId) === normalizeSuiAddress(packageId))
76
+ return d;
77
+ }
78
+ return null;
79
+ }
80
+ }
package/dist/plugin.js CHANGED
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import { spawn } from 'node:child_process';
10
10
  import { randomUUID } from 'node:crypto';
11
- import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
11
+ import { mkdir, readdir, writeFile } from 'node:fs/promises';
12
12
  import { createServer } from 'node:http';
13
13
  import { homedir } from 'node:os';
14
14
  import { basename, dirname, join, resolve } from 'node:path';
@@ -21,8 +21,9 @@ import { Transaction } from '@mysten/sui/transactions';
21
21
  import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
22
22
  import { z } from 'zod';
23
23
  import { clientFor, deepbookSizes, findPools, quoteSwap, readAllHoldings, readHoldings, readStatus, withMarketFacts, } from './chain.js';
24
+ import { Deployments } from './deployments.js';
24
25
  import { describePolicy, describeSetup, renderRows } from './describe.js';
25
- import { address, coinBySymbol, coinInfo, connects, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, MAX_TERM_DAYS, poolsFor, recipientName, requiredSui, sameCoin, SetupSchema, showCoin, SUI, uncovered, units, VenueSchema, } from './domain.js';
26
+ 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';
26
27
  import { passIdOf } from './explorer.js';
27
28
  import { passEnded, returnGasFloat } from './float.js';
28
29
  import { failure, INSTRUCTIONS, keyAlert, MAX_TOOL_INPUT_ELEMENTS, registerDocs, result, serverInfo, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
@@ -46,13 +47,14 @@ export function cliInvocation() {
46
47
  ? [process.execPath, entry]
47
48
  : [join(repoRoot, 'node_modules/.bin/tsx'), entry.replace(/\.js$/, '.ts')];
48
49
  }
49
- const exists = (path) => access(path).then(() => true, () => false);
50
50
  /** Every session directory under the root, opened lazily and kept for the process lifetime. */
51
51
  class Registry {
52
52
  options;
53
53
  sessions = new Map();
54
+ deployments;
54
55
  constructor(options) {
55
56
  this.options = options;
57
+ this.deployments = new Deployments(options.root, options.deployment);
56
58
  }
57
59
  get sessionsDir() {
58
60
  return join(this.options.root, 'sessions');
@@ -74,7 +76,7 @@ class Registry {
74
76
  try {
75
77
  this.sessions.set(id, {
76
78
  id,
77
- store: await SessionStore.open(join(this.sessionsDir, id), (network, packageId) => this.current(network, packageId)),
79
+ store: await SessionStore.open(join(this.sessionsDir, id), (network, packageId) => this.deployments.current(network, packageId)),
78
80
  });
79
81
  this.unreadable.delete(id);
80
82
  }
@@ -138,33 +140,6 @@ class Registry {
138
140
  async close() {
139
141
  await Promise.all([...this.sessions.values()].map((s) => s.server?.close()));
140
142
  }
141
- deploymentPath(override) {
142
- return resolve(override ?? this.options.deployment ?? join(this.options.root, 'deployment.json'));
143
- }
144
- /** The networks this package ships a deployment for, in the order a new pass defaults to. */
145
- async bundledNetworks() {
146
- const all = ['mainnet', 'testnet', 'devnet'];
147
- const present = await Promise.all(all.map((n) => exists(this.bundledPath(n))));
148
- return all.filter((_, i) => present[i]);
149
- }
150
- bundledPath(network) {
151
- return fileURLToPath(new URL(`../deployments/${network}.json`, import.meta.url));
152
- }
153
- /** Today's deployment for a network when it is the same package: the private file first, else the bundled one. */
154
- async current(network, packageId) {
155
- const candidates = [
156
- () => this.deployment().catch(() => null),
157
- () => this.bundled(network).catch(() => null),
158
- ];
159
- for (const read of candidates) {
160
- const d = await read();
161
- if (d &&
162
- d.network === network &&
163
- normalizeSuiAddress(d.packageId) === normalizeSuiAddress(packageId))
164
- return d;
165
- }
166
- return null;
167
- }
168
143
  /**
169
144
  * Retires a session directory once its pass is over: refuses while the pass is live, returns
170
145
  * the key's gas float to the owner first, then deletes the directory and its key. Works on a
@@ -175,7 +150,9 @@ class Registry {
175
150
  const session = this.sessions.get(id);
176
151
  const peek = await SessionStore.peek(dir);
177
152
  const d = session?.store.state.deployment ??
178
- (peek.network && peek.packageId ? await this.current(peek.network, peek.packageId) : null);
153
+ (peek.network && peek.packageId
154
+ ? await this.deployments.current(peek.network, peek.packageId)
155
+ : null);
179
156
  if (peek.passId) {
180
157
  if (!d)
181
158
  throw new Error('No deployment known for this session; cannot tell whether its pass is live');
@@ -191,24 +168,6 @@ class Registry {
191
168
  await SessionStore.forget(dir);
192
169
  return { swept };
193
170
  }
194
- async bundled(network) {
195
- return DeploymentSchema.parse(JSON.parse(await readFile(this.bundledPath(network), 'utf8')));
196
- }
197
- /**
198
- * Where a new pass goes: an explicit file, else the private `deployment.json` under the root
199
- * (a publish of one's own), else the deployment bundled for `network`, else the first bundled
200
- * one. A user who installed the package has only the bundled ones and needs no file.
201
- */
202
- async deployment(override, network) {
203
- const configured = this.deploymentPath(override);
204
- if (override || this.options.deployment || (await exists(configured)))
205
- return DeploymentSchema.parse(JSON.parse(await readFile(configured, 'utf8')));
206
- const bundled = await this.bundledNetworks();
207
- const chosen = network ?? bundled[0];
208
- if (!chosen || !(network === undefined || bundled.includes(network)))
209
- throw new Error(`No deployment for ${network ?? 'any network'}: this package ships ${bundled.join(', ') || 'none'}, and there is no ${configured}.`);
210
- return this.bundled(chosen);
211
- }
212
171
  }
213
172
  const decimal = z.string().regex(/^[0-9]+(\.[0-9]+)?$/, 'decimal number');
214
173
  const symbol = z
@@ -429,7 +388,8 @@ export function createPluginMcp(registry) {
429
388
  },
430
389
  annotations: { readOnlyHint: true },
431
390
  }, async ({ owner }) => {
432
- const path = registry.deploymentPath();
391
+ const path = registry.deployments.path();
392
+ const migration = await registry.deployments.migrationNotice();
433
393
  const markets = async (d) => ({
434
394
  network: d.network,
435
395
  maxTermDays: d.maxTermDays,
@@ -451,8 +411,8 @@ export function createPluginMcp(registry) {
451
411
  ? { ownerCoins: await readAllHoldings(clientFor(d), d, owner).catch(() => null) }
452
412
  : {}),
453
413
  });
454
- const own = (await exists(path)) ? [await markets(await registry.deployment())] : [];
455
- const bundled = await Promise.all((await registry.bundledNetworks()).map(async (n) => markets(await registry.bundled(n))));
414
+ const own = path === undefined ? [] : [await markets(await registry.deployments.load())];
415
+ const bundled = await Promise.all((await registry.deployments.bundledNetworks()).map(async (n) => markets(await registry.deployments.bundled(n))));
456
416
  const passes = await Promise.all((await registry.all()).map(summaryWithChain));
457
417
  const unreadable = [...registry.unreadable.values()];
458
418
  return result({
@@ -463,7 +423,11 @@ export function createPluginMcp(registry) {
463
423
  unreadableNote: 'These sessions were written by an earlier version of this package and cannot be used from here. Their passes may still be live: tell the owner, and have them stop or close each one from the pass page of the site (#/pass/<passId>), which reads the chain and needs no session file.',
464
424
  }
465
425
  : {}),
466
- deployment: { path, exists: own.length > 0 },
426
+ deployment: {
427
+ source: path === undefined ? 'bundled' : 'custom',
428
+ ...(path === undefined ? {} : { path }),
429
+ ...(migration ? { migration } : {}),
430
+ },
467
431
  server: await serverInfo(),
468
432
  networks: [...own, ...bundled.filter((b) => !own.some((o) => o.network === b.network))],
469
433
  });
@@ -481,7 +445,7 @@ export function createPluginMcp(registry) {
481
445
  annotations: { readOnlyHint: true, openWorldHint: true },
482
446
  }, async ({ coin, with: other, network }) => {
483
447
  try {
484
- const d0 = await registry.deployment(undefined, network);
448
+ const d0 = await registry.deployments.load(undefined, network);
485
449
  const type = (s) => (/::/.test(s) ? s : coinBySymbol(d0, s).type);
486
450
  const { d, found } = await findPools(clientFor(d0), d0, type(coin), other ? type(other) : undefined);
487
451
  const priced = await Promise.all(found.map(async ({ pool, tvlUsd }) => ({
@@ -526,11 +490,11 @@ export function createPluginMcp(registry) {
526
490
  network: z
527
491
  .enum(['mainnet', 'testnet', 'devnet', 'localnet'])
528
492
  .optional()
529
- .describe('which network the pass lives on, from the deployments this package ships; omit for the default (a private deployment.json under the root, else the first shipped network)'),
493
+ .describe('which network the pass lives on, from the deployments this package ships; omit for the explicitly configured deployment or first shipped network. If list_passes reports a deployment migration, ask the owner to choose before proposing. Must match any explicitly selected deployment.'),
530
494
  deployment: z
531
495
  .string()
532
496
  .optional()
533
- .describe('path of a private deployment.json; overrides network'),
497
+ .describe('explicit path of a custom deployment.json; must match network when both are supplied'),
534
498
  owner: address
535
499
  .optional()
536
500
  .describe("the owner's address, when they gave it: adds warnings where the caps reach past what they hold, or when they cannot sign yet"),
@@ -538,7 +502,7 @@ export function createPluginMcp(registry) {
538
502
  annotations: { readOnlyHint: false, destructiveHint: false },
539
503
  }, async ({ deployment, network, owner, ...input }) => {
540
504
  try {
541
- const d0 = await registry.deployment(deployment, network);
505
+ const d0 = await registry.deployments.load(deployment, network);
542
506
  const { setup, d } = await toSetup(clientFor(d0), d0, input);
543
507
  const session = await registry.create(d, setup);
544
508
  const { ownerUrl } = await registry.server(session);
package/docs/PLAYBOOK.md CHANGED
@@ -110,7 +110,12 @@ ask for a yes, unless they already stated every rule explicitly.
110
110
  machine. A per-session HTTP signer has only `session_info` and `sign_transaction`.
111
111
 
112
112
  The pass goes on the network the owner names (`network`, one of `list_passes.networks`), else on
113
- the first network listed. A private publish of one's own takes a `deployment` path instead.
113
+ the first network listed. A private publish of one's own takes an explicit `deployment` path
114
+ instead (or the server starts with `--deployment`). If both a file and a network are selected,
115
+ they must match. A file left at `~/.sui-agent-pass/deployment.json` is never loaded automatically.
116
+ If `list_passes.deployment.migration` is present, show it and ask the owner which network or
117
+ custom deployment to use before making a new proposal. Never pick a network or change files
118
+ just to clear that message. Existing passes retain their deployment.
114
119
 
115
120
  Call `propose_authorization` with the rules. It returns `rules`, the exact text the review page
116
121
  shows, plus `reviewUrl` and `sessionAddress`, and opens the page in the browser. Paste `rules` to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mysten-incubation/sui-agent-pass",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
4
4
  "type": "module",
5
5
  "description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
6
6
  "repository": {
@@ -115,7 +115,12 @@ ask for a yes, unless they already stated every rule explicitly.
115
115
  machine. A per-session HTTP signer has only `session_info` and `sign_transaction`.
116
116
 
117
117
  The pass goes on the network the owner names (`network`, one of `list_passes.networks`), else on
118
- the first network listed. A private publish of one's own takes a `deployment` path instead.
118
+ the first network listed. A private publish of one's own takes an explicit `deployment` path
119
+ instead (or the server starts with `--deployment`). If both a file and a network are selected,
120
+ they must match. A file left at `~/.sui-agent-pass/deployment.json` is never loaded automatically.
121
+ If `list_passes.deployment.migration` is present, show it and ask the owner which network or
122
+ custom deployment to use before making a new proposal. Never pick a network or change files
123
+ just to clear that message. Existing passes retain their deployment.
119
124
 
120
125
  Call `propose_authorization` with the rules. It returns `rules`, the exact text the review page
121
126
  shows, plus `reviewUrl` and `sessionAddress`, and opens the page in the browser. Paste `rules` to