@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 +6 -1
- package/dist/cli.js +95 -65
- package/dist/connect-ui.js +85 -0
- package/package.json +1 -1
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.
|
|
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
|
-
.
|
|
107
|
-
.
|
|
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
|
-
|
|
127
|
+
detail(`Updated ${path}`);
|
|
112
128
|
}
|
|
113
|
-
/**
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
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
|
|
129
|
-
|
|
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
|
-
|
|
190
|
+
await mergeJsonConfig(path, stdio, detail);
|
|
191
|
+
return;
|
|
180
192
|
}
|
|
181
193
|
case 'cursor':
|
|
182
|
-
|
|
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
|
-
|
|
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'],
|
|
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
|
-
|
|
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'],
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
376
|
-
|
|
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
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
console.log(
|
|
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
|
+
}
|