@mysten-incubation/sui-agent-pass 0.1.20 → 0.1.22

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
@@ -218,7 +218,12 @@ Register the agents that may use your passes once with `connect`. It shows the d
218
218
  and offers to connect them all, or choose specific ones. **Other / manual setup** offers
219
219
  undetected clients, Cursor and a generic MCP configuration; Cursor is excluded from detection
220
220
  and bulk setup. You can also select a client directly with `--client <name>`. After connecting,
221
- restart each connected agent and start a new chat session. Then start Claude anywhere:
221
+ restart each connected agent and start a new chat session. The terminal shows a compact status
222
+ for each agent: green for connected, yellow for manual or incomplete setup, and red for failure.
223
+ Colors are disabled for redirected output and `NO_COLOR`. Use `agent-pass connect --verbose`
224
+ to see native setup output and configuration/skill paths. Claude Desktop receives the playbook
225
+ through MCP; optionally add the packaged skill in its settings (the path is shown with `--verbose`).
226
+ Then start Claude anywhere:
222
227
 
223
228
  ```sh
224
229
  claude
package/dist/cli.js CHANGED
@@ -7,10 +7,11 @@ import { access, cp, lstat, mkdir, readFile, rm, symlink, writeFile } from 'node
7
7
  import { homedir } from 'node:os';
8
8
  import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
9
9
  import { fileURLToPath } from 'node:url';
10
- import { promisify } from 'node:util';
10
+ import { promisify, stripVTControlCharacters } from 'node:util';
11
11
  import { checkbox, select } from '@inquirer/prompts';
12
12
  import { Command } from 'commander';
13
13
  import { clientFor, readStatus } from './chain.js';
14
+ import { ConnectUI } from './connect-ui.js';
14
15
  import { cliInvocation, defaultRoot, forgetSession, openBrowser, servePlugin, servePluginHttp, } from './plugin.js';
15
16
  import { startServer } from './server.js';
16
17
  import { SessionStore } from './storage.js';
@@ -101,45 +102,55 @@ function openclawArgs(args) {
101
102
  return profile ? ['--profile', profile, ...args] : args;
102
103
  }
103
104
  /** Merges one server entry into a JSON MCP config file, creating it if needed. */
104
- async function mergeJsonConfig(path, entry) {
105
+ async function mergeJsonConfig(path, entry, detail) {
105
106
  const current = await readFile(path, 'utf8')
106
- .then((t) => JSON.parse(t))
107
- .catch(() => ({}));
107
+ .catch((error) => {
108
+ if (error.code === 'ENOENT')
109
+ return '{}';
110
+ throw error;
111
+ })
112
+ .then((text) => {
113
+ try {
114
+ const config = JSON.parse(text);
115
+ const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
116
+ if (!object(config) || (config.mcpServers !== undefined && !object(config.mcpServers)))
117
+ throw new Error('Invalid config structure');
118
+ return config;
119
+ }
120
+ catch {
121
+ throw new Error(`Fix the invalid MCP configuration in ${path}, then try again. The file was not changed.`);
122
+ }
123
+ });
108
124
  current.mcpServers = { ...(current.mcpServers ?? {}), 'agent-pass': entry };
109
125
  await mkdir(dirname(path), { recursive: true });
110
126
  await writeFile(path, JSON.stringify(current, null, 2) + '\n', { mode: 0o600 });
111
- console.log(`Wrote agent-pass into ${path}.`);
127
+ detail(`Updated ${path}`);
112
128
  }
113
- /** Registers agent-pass with Claude Code, replacing an earlier entry in the same scope. */
114
- /** Runs a client's own CLI; the client is not on this machine when the command cannot start. */
115
- function cli(bin, args, quiet = false) {
116
- return new Promise((resolve, reject) => {
117
- const child = spawn(bin, args, { stdio: quiet ? 'ignore' : 'inherit' });
118
- child.once('error', (e) => reject(e.code === 'ENOENT'
119
- ? new Error(`${bin} is not on PATH; install it or pick another client`)
120
- : e));
121
- child.once('exit', (code) => code === 0
122
- ? resolve()
123
- : reject(new Error(`${bin} ${args.slice(0, 2).join(' ')} exited ${code}`)));
124
- });
129
+ /** Capture native setup chatter; preserve useful errors without echoing command arguments/tokens. */
130
+ async function cli(bin, args, detail) {
131
+ try {
132
+ const { stdout, stderr } = await promisify(execFile)(bin, args);
133
+ detail([stdout, stderr].filter(Boolean).join('\n'));
134
+ return stdout;
135
+ }
136
+ catch (error) {
137
+ const failure = error;
138
+ const output = stripVTControlCharacters(failure.stderr?.trim() || failure.stdout?.trim() || '');
139
+ detail(`${bin}: ${failure.signal ?? failure.code ?? 'process error'}\n${output}`);
140
+ if (failure.code === 'ENOENT')
141
+ throw new Error(`${bin} was not found. Install it, then run connect again.`);
142
+ const reason = output.split('\n').filter(Boolean).slice(0, 4).join('\n');
143
+ throw new Error(`${bin} could not finish setup.${reason ? `\n${reason}` : ` Exit: ${failure.signal ?? failure.code ?? 'unknown'}.`}`);
144
+ }
125
145
  }
126
- async function claudeMcpAdd(args) {
146
+ /** Registers agent-pass with Claude Code, replacing an earlier entry in the same scope. */
147
+ async function claudeMcpAdd(args, detail) {
127
148
  const scope = args[args.indexOf('--scope') + 1];
128
- await new Promise((done) => {
129
- const remove = spawn('claude', ['mcp', 'remove', '--scope', scope, 'agent-pass'], {
130
- stdio: 'ignore',
131
- });
132
- remove.once('error', () => done());
133
- remove.once('exit', () => done());
134
- });
135
- const child = spawn('claude', ['mcp', 'add', ...args], { stdio: 'inherit' });
136
- await new Promise((resolve, reject) => {
137
- child.once('error', reject);
138
- child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`claude mcp add exited ${code}`)));
139
- });
149
+ await cli('claude', ['mcp', 'remove', '--scope', scope, 'agent-pass'], () => { }).catch(() => { });
150
+ await cli('claude', ['mcp', 'add', ...args], detail);
140
151
  }
141
152
  /** Writes the signer into one client's MCP configuration; the stdio form needs no running process. */
142
- async function registerClient(client, http) {
153
+ async function registerClient(client, http, detail) {
143
154
  const [command, ...args] = cliInvocation();
144
155
  const stdio = { command, args: [...args, 'mcp'] };
145
156
  const home = homedir();
@@ -155,7 +166,7 @@ async function registerClient(client, http) {
155
166
  http.url,
156
167
  '--header',
157
168
  http.headers.Authorization,
158
- ]);
169
+ ], detail);
159
170
  else
160
171
  await claudeMcpAdd([
161
172
  '--transport',
@@ -166,7 +177,7 @@ async function registerClient(client, http) {
166
177
  '--',
167
178
  stdio.command,
168
179
  ...stdio.args,
169
- ]);
180
+ ], detail);
170
181
  return;
171
182
  case 'claude-desktop': {
172
183
  if (http)
@@ -176,40 +187,30 @@ async function registerClient(client, http) {
176
187
  : process.platform === 'win32'
177
188
  ? join(process.env.APPDATA ?? join(home, 'AppData/Roaming'), 'Claude/claude_desktop_config.json')
178
189
  : join(home, '.config/Claude/claude_desktop_config.json');
179
- return mergeJsonConfig(path, stdio);
190
+ await mergeJsonConfig(path, stdio, detail);
191
+ return;
180
192
  }
181
193
  case 'cursor':
182
- return mergeJsonConfig(join(home, '.cursor/mcp.json'), http ?? stdio);
194
+ await mergeJsonConfig(join(home, '.cursor/mcp.json'), http ?? stdio, detail);
195
+ return;
183
196
  case 'hermes': {
184
197
  // `hermes mcp add` writes ~/.hermes/config.yaml itself; an HTTP signer's bearer header
185
198
  // has no plain flag there, so that form is printed to paste.
186
199
  if (http) {
187
- console.log(`Add to ~/.hermes/config.yaml under mcp_servers:\n\n agent-pass:\n url: "${http.url}"\n headers:\n Authorization: "${http.headers.Authorization}"\n`);
188
- return;
200
+ return `Add to ~/.hermes/config.yaml under mcp_servers:\n\n agent-pass:\n url: "${http.url}"\n headers:\n Authorization: "${http.headers.Authorization}"`;
189
201
  }
190
- await cli('hermes', ['mcp', 'remove', 'agent-pass'], true).catch(() => { });
191
- await cli('hermes', [
192
- 'mcp',
193
- 'add',
194
- 'agent-pass',
195
- '--command',
196
- stdio.command,
197
- '--args',
198
- ...stdio.args,
199
- ]);
200
- console.log('Registered agent-pass with Hermes (hermes mcp add).');
202
+ await cli('hermes', ['mcp', 'remove', 'agent-pass'], () => { }).catch(() => { });
203
+ await cli('hermes', ['mcp', 'add', 'agent-pass', '--command', stdio.command, '--args', ...stdio.args], detail);
201
204
  return;
202
205
  }
203
206
  case 'codex': {
204
207
  // `codex mcp add` writes ~/.codex/config.toml itself; an HTTP signer's bearer header has
205
208
  // no flag there, so that form is printed to paste.
206
209
  if (http) {
207
- console.log(`Add to ~/.codex/config.toml:\n\n[mcp_servers.agent-pass]\nurl = "${http.url}"\nhttp_headers = { Authorization = "${http.headers.Authorization}" }\n`);
208
- return;
210
+ return `Add to ~/.codex/config.toml:\n\n[mcp_servers.agent-pass]\nurl = "${http.url}"\nhttp_headers = { Authorization = "${http.headers.Authorization}" }`;
209
211
  }
210
- await cli('codex', ['mcp', 'remove', 'agent-pass'], true).catch(() => { });
211
- await cli('codex', ['mcp', 'add', 'agent-pass', '--', stdio.command, ...stdio.args]);
212
- console.log('Registered agent-pass with Codex (codex mcp add).');
212
+ await cli('codex', ['mcp', 'remove', 'agent-pass'], () => { }).catch(() => { });
213
+ await cli('codex', ['mcp', 'add', 'agent-pass', '--', stdio.command, ...stdio.args], detail);
213
214
  return;
214
215
  }
215
216
  case 'openclaw':
@@ -223,10 +224,10 @@ async function registerClient(client, http) {
223
224
  ...(http ? { ...http, transport: 'streamable-http' } : stdio),
224
225
  requestTimeoutMs: 180_000, // session_info can wait 120 seconds for wallet consent.
225
226
  }),
226
- ]));
227
+ ]), detail);
227
228
  return;
228
229
  case 'json':
229
- console.log(JSON.stringify({ mcpServers: { 'agent-pass': http ?? stdio } }, null, 2));
230
+ return `Add this to your agent's MCP settings:\n\n${JSON.stringify({ mcpServers: { 'agent-pass': http ?? stdio } }, null, 2)}`;
230
231
  }
231
232
  }
232
233
  /** Where each agent loads personal skills from, under the home directory. */
@@ -240,21 +241,21 @@ const SKILL_DIRS = {
240
241
  * Puts the agent-pass skill, the playbook built into this package, where the client loads
241
242
  * skills. A link follows upgrades of the package; an npx cache is temporary, so it gets a copy.
242
243
  */
243
- async function installSkill(client) {
244
+ async function installSkill(client, detail) {
244
245
  const source = fileURLToPath(new URL('../skills/agent-pass', import.meta.url));
245
246
  if (!(await access(join(source, 'SKILL.md')).then(() => true, () => false)))
246
247
  throw new Error(`The skill is missing from ${source}; run npm run build`);
247
248
  let dir = SKILL_DIRS[client];
248
249
  if (client === 'openclaw') {
249
250
  // Ask the client for its managed directory so profiles and custom state roots stay aligned.
250
- const { stdout } = await promisify(execFile)('openclaw', openclawArgs(['skills', 'list', '--json']));
251
+ const stdout = await cli('openclaw', openclawArgs(['skills', 'list', '--json']), () => { });
251
252
  const report = JSON.parse(stdout);
252
253
  if (typeof report.managedSkillsDir !== 'string' || !isAbsolute(report.managedSkillsDir))
253
254
  throw new Error('OpenClaw did not report an absolute managed skills directory');
254
255
  dir = report.managedSkillsDir;
255
256
  }
256
257
  if (!dir) {
257
- console.log(client === 'claude-desktop'
258
+ detail(client === 'claude-desktop'
258
259
  ? `Claude Desktop takes skills from its own settings; add ${join(source, 'SKILL.md')} there to give it the playbook.`
259
260
  : `If the agent loads SKILL.md skills, link ${source} into its skills folder to give it the playbook.`);
260
261
  return;
@@ -274,7 +275,7 @@ async function installSkill(client) {
274
275
  await cp(source, target, { recursive: true });
275
276
  else
276
277
  await symlink(source, target, 'dir');
277
- console.log(`${temporary ? 'Copied' : 'Linked'} the agent-pass skill into ${target}.`);
278
+ detail(`${temporary ? 'Copied' : 'Linked'} skill: ${target}`);
278
279
  }
279
280
  /** Connect detected agents together; Cursor and undetected clients stay in manual setup. */
280
281
  async function chooseClients(http = false) {
@@ -359,6 +360,7 @@ program
359
360
  .description("Register the signer with an agent client. By default the stdio server over every pass on this machine, which the client starts when it needs it. --session registers one session's running HTTP signer (serve) instead.")
360
361
  .option('--session <directory>')
361
362
  .option('--client <client>', `one of ${CLIENTS.join(', ')}; asked when omitted`)
363
+ .option('--verbose', 'Show setup details and configuration paths')
362
364
  .action(async (o) => {
363
365
  if (o.client && !CLIENTS.includes(o.client))
364
366
  throw new Error(`Unknown client '${o.client}'`);
@@ -370,16 +372,44 @@ program
370
372
  const { mcpUrl } = JSON.parse(await readFile(join(store.directory, 'runtime.json'), 'utf8'));
371
373
  http = { url: mcpUrl, headers: { Authorization: `Bearer ${await store.mcpToken()}` } };
372
374
  }
375
+ const ui = new ConnectUI(!!o.verbose, http ? [http.headers.Authorization] : []);
376
+ ui.heading();
373
377
  const clients = o.client ? [o.client] : await chooseClients(!!http);
378
+ if (!clients.length)
379
+ return;
380
+ if (!o.client)
381
+ console.log();
382
+ const width = Math.max(...clients.map((client) => CLIENT_NAMES[client].length));
383
+ const ready = [];
384
+ const manual = [];
385
+ let failed = false;
374
386
  for (const client of clients) {
375
- await registerClient(client, http);
376
- await installSkill(client);
387
+ const name = CLIENT_NAMES[client];
388
+ ui.start(name);
389
+ let registered = false;
390
+ try {
391
+ const instructions = await registerClient(client, http, ui.detail);
392
+ registered = instructions === undefined;
393
+ if (instructions)
394
+ manual.push({ name, instructions });
395
+ await installSkill(client, ui.detail);
396
+ ui.finish(name, instructions ? 'Setup needed' : 'Connected', width);
397
+ ready.push(client === 'json' ? 'your agent' : name);
398
+ }
399
+ catch (error) {
400
+ ui.finish(name, registered ? 'Setup incomplete' : 'Failed', width, error);
401
+ failed = true;
402
+ }
377
403
  }
378
- if (clients.length) {
379
- const manual = clients.some((client) => client === 'json' || (http && (client === 'codex' || client === 'hermes')));
380
- const names = clients.map((client) => client === 'json' ? 'your agent' : CLIENT_NAMES[client]);
381
- console.log(`\n${manual ? 'After adding the configuration above:' : 'Connected.'}\n1. Restart ${names.join(', ')}.\n2. Start a new chat session${clients.length > 1 ? ' in each' : ''}.`);
404
+ for (const { name, instructions } of manual)
405
+ ui.manual(name, instructions);
406
+ if (failed) {
407
+ console.log('\n Resolve the issue above, then run connect again.\n Use --verbose to see setup details.');
408
+ process.exitCode = 1;
382
409
  }
410
+ ui.next(ready, manual.length > 0);
411
+ if (!ready.length)
412
+ console.log();
383
413
  });
384
414
  // Run only when this file is the entry: directly, through tsx in development, or through the
385
415
  // package's `agent-pass` bin, which is a symlink to it.
@@ -0,0 +1,85 @@
1
+ // Copyright (c) Mysten Labs, Inc.
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { stripVTControlCharacters, styleText } from 'node:util';
4
+ const STATUS = {
5
+ Connected: { symbol: '✓', color: 'green' },
6
+ 'Setup needed': { symbol: '!', color: 'yellow' },
7
+ 'Setup incomplete': { symbol: '!', color: 'yellow' },
8
+ Failed: { symbol: '✗', color: 'red' },
9
+ };
10
+ /** Presentation only: registration and skill installation stay with each client's setup. */
11
+ export class ConnectUI {
12
+ verbose;
13
+ secrets;
14
+ timer;
15
+ details = [];
16
+ terminal = !!process.stdout.isTTY && process.env.TERM !== 'dumb';
17
+ color = this.terminal &&
18
+ process.env.NO_COLOR === undefined &&
19
+ process.env.NODE_DISABLE_COLORS !== '1' &&
20
+ process.env.FORCE_COLOR !== '0';
21
+ constructor(verbose, secrets = []) {
22
+ this.verbose = verbose;
23
+ this.secrets = secrets;
24
+ }
25
+ style(format, text) {
26
+ return this.color ? styleText(format, text, { validateStream: false }) : text;
27
+ }
28
+ clean(text) {
29
+ for (const secret of this.secrets)
30
+ text = text.replaceAll(secret, '[redacted]');
31
+ return stripVTControlCharacters(text).trim();
32
+ }
33
+ heading() {
34
+ console.log(`\n ${this.style(['bold', 'cyan'], 'Agent Pass')}\n`);
35
+ }
36
+ start(name) {
37
+ this.details = [];
38
+ if (!this.terminal || process.stdout.columns < name.length + 24)
39
+ return;
40
+ const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
41
+ let frame = 0;
42
+ const draw = () => process.stdout.write(`\r\x1b[2K ${this.style('cyan', frames[frame++ % frames.length])} ${name} ${this.style('dim', 'Connecting…')}`);
43
+ draw();
44
+ this.timer = setInterval(draw, 90);
45
+ this.timer.unref();
46
+ }
47
+ detail = (text) => {
48
+ if (this.verbose && text.trim())
49
+ this.details.push(this.clean(text));
50
+ };
51
+ finish(name, status, width, error) {
52
+ if (this.timer) {
53
+ clearInterval(this.timer);
54
+ this.timer = undefined;
55
+ process.stdout.write('\r\x1b[2K');
56
+ }
57
+ const { symbol, color } = STATUS[status];
58
+ console.log(` ${this.style(color, symbol)} ${name.padEnd(width + 3)}${this.style(color, status)}`);
59
+ if (error) {
60
+ const message = this.clean(error instanceof Error ? error.message : String(error));
61
+ console.log(message
62
+ .split('\n')
63
+ .map((line) => ` ${line}`)
64
+ .join('\n'));
65
+ }
66
+ for (const detail of this.details)
67
+ console.log(this.style('dim', detail
68
+ .split('\n')
69
+ .map((line) => ` ${line}`)
70
+ .join('\n')));
71
+ }
72
+ manual(name, instructions) {
73
+ console.log(`\n ${this.style('bold', `${name} · Manual setup`)}\n\n${instructions}`);
74
+ }
75
+ next(names, manual) {
76
+ if (!names.length)
77
+ return;
78
+ const who = names.length === 1 ? names[0] : 'the connected agents';
79
+ console.log(`\n ${this.style('bold', 'Next steps')}`);
80
+ if (manual)
81
+ console.log(' Complete the manual setup above first.');
82
+ console.log(` 1. Restart ${who}.`);
83
+ console.log(` 2. Start a new chat session${names.length > 1 ? ' in each' : ''}.\n`);
84
+ }
85
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mysten-incubation/sui-agent-pass",
3
- "version": "0.1.20",
3
+ "version": "0.1.22",
4
4
  "type": "module",
5
5
  "description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
6
6
  "repository": {