passcontrol 0.5.3 → 0.6.1

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.
@@ -24,6 +24,9 @@ import {
24
24
  ok,
25
25
  redact,
26
26
  requireControlApiKey,
27
+ requireControlGateway,
28
+ operatorEnv,
29
+ requirePassportGateway,
27
30
  requirePassport,
28
31
  step,
29
32
  warn,
@@ -125,48 +128,65 @@ function cliCommand(args = "") {
125
128
 
126
129
  function usage() {
127
130
  const cmd = cliPrefix();
128
- return `${heading("PassControl")}
131
+ return `${heading(`PassControl ${CLI_VERSION}`)}
132
+ Governed identity and credentials for AI agents.
129
133
 
130
134
  ${heading("Usage:")}
131
135
  ${cmd} show cockpit status
132
- ${cmd} init [--global] create a config profile
133
- ${cmd} status [--no-network] show active config
136
+ ${cmd} <command> [options]
137
+
138
+ ${heading("Quick start")}
139
+ ${cmd} init [--global] configure this project
134
140
  ${cmd} start [--dashboard-only] start the whole local stack (dashboard + Supabase + Redis)
141
+ ${cmd} open start if needed and open the Control Tower
142
+ ${cmd} try run the 60-second keyless guided demo
143
+
144
+ ${heading("Operate")}
145
+ ${cmd} status [--no-network] [--json]
146
+ show active config and instance state
147
+ ${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
148
+ ${cmd} call "hi" mint a visa and make a governed model call
149
+ ${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
150
+ start the local agent bridge
151
+
152
+ ${heading("Manage")}
153
+ ${cmd} agent list [--json] list agents
154
+ ${cmd} agent create <name> create an agent passport
155
+ ${cmd} agent rotate <id> [--grace <seconds>]
156
+ rotate locally and reveal the new secret once
157
+ ${cmd} agent suspend <id> suspend an agent
158
+ ${cmd} agent resume <id> resume an agent
159
+ ${cmd} agent revoke <id> permanently revoke an agent
160
+ ${cmd} spend [--json] show fleet and per-agent spend
161
+ ${cmd} audit [--limit 20] [--json]
162
+ show operator audit history
163
+ ${cmd} logs [--limit 20] [--json]
164
+ show governed call logs
165
+ ${cmd} kill on|off toggle the tenant kill switch
166
+
167
+ ${heading("Integrate")}
168
+ ${cmd} env [integration] print settings without writing anything
169
+ ${cmd} configure <integration> [--write] [--force]
170
+ preview or write integration config
171
+ ${cmd} mcp start the stdio MCP server
172
+ integrations: ${integrationChoices()}
173
+
174
+ ${heading("Trust")}
175
+ ${cmd} keygen instance create the receipt-signing key
176
+ ${cmd} verify receipt <jws> --issuer <origin>
177
+ verify a signed call receipt
178
+ ${cmd} verify token <jwt> --audience <aud> --issuer <origin>
179
+ verify an agent-to-agent token
180
+
181
+ ${heading("Local stack")}
182
+ ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
183
+ clone if needed, start services, open dashboard
135
184
  ${cmd} stop [--dashboard-only] stop the whole local stack (dashboard + Supabase + Redis)
136
185
  ${cmd} restart restart the CLI-managed local dashboard
137
186
  ${cmd} local-logs [--follow] show local dashboard logs
138
- ${cmd} doctor [--deep] [--fix] check local setup and repair a stopped dashboard
139
187
  ${cmd} reset --local --confirm RESET
140
188
  destroy and recreate the local stack
141
- ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
142
- clone the app (if needed), start local services, open the dashboard
143
- --app-dir repoints the CLI and is remembered
144
189
  ${cmd} unlink forget the remembered app checkout
145
- ${cmd} try 60-second demo: governed keyless call + kill switch (no key)
146
- ${cmd} call "hi" mint a visa and call a model
147
- ${cmd} sidecar [--port 8788] start the local agent bridge
148
- ${cmd} mcp start the local stdio MCP server
149
- ${cmd} configure <integration> [--write] [--force]
150
- set up an integration: previews the config, and
151
- --write creates it for aider|claude-desktop|cursor
152
- ${cmd} env [integration] print the same settings without writing anything
153
- (defaults to generic)
154
- <integration>: ${integrationChoices()}
155
- ${cmd} agent list list agents
156
- ${cmd} agent create <name> create an agent passport
157
- ${cmd} agent suspend <id> suspend an agent
158
- ${cmd} agent resume <id> resume an agent
159
- ${cmd} agent revoke <id> revoke an agent
160
- ${cmd} spend show fleet + per-agent spend
161
- ${cmd} audit [--limit 20] show admin audit trail
162
- ${cmd} logs [--limit 20] show gateway call logs
163
- ${cmd} kill on|off toggle tenant kill switch
164
- ${cmd} keygen instance generate the deployment's receipt-signing key
165
- ${cmd} verify receipt <jws> --issuer <origin>
166
- check a signed call receipt (no account needed)
167
- ${cmd} verify token <jwt> --audience <aud> --issuer <origin>
168
- check an agent-to-agent token
169
- ${cmd} open start (if needed) and open the dashboard
170
190
 
171
191
  ${heading("Config:")}
172
192
  Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
@@ -178,6 +198,30 @@ ${heading("Config:")}
178
198
  `;
179
199
  }
180
200
 
201
+ function agentUsage() {
202
+ const cmd = cliPrefix();
203
+ return `${heading("Manage agent passports")}
204
+
205
+ ${heading("Usage:")}
206
+ ${cmd} agent list
207
+ ${cmd} agent create <name> [--provider <provider>] [--scope <model-pattern>]
208
+ ${cmd} agent rotate <id> [--grace <seconds>]
209
+ ${cmd} agent suspend <id>
210
+ ${cmd} agent resume <id>
211
+ ${cmd} agent revoke <id>
212
+
213
+ ${heading("Examples")}
214
+ ${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
215
+ ${cmd} agent rotate <id> --grace 3600
216
+ ${cmd} agent suspend <id>
217
+
218
+ Create and rotate generate the Ed25519 private key on this machine. Only the
219
+ public key crosses the control API. The private key is shown once; store it
220
+ before leaving the command. During rotation grace, both old and new keys work.
221
+ Revocation is permanent; suspension is reversible.
222
+ `;
223
+ }
224
+
181
225
  function assertProvider(provider) {
182
226
  if (!PROVIDERS.includes(provider)) {
183
227
  throw new Error(`Unknown provider "${provider}". Use one of: ${PROVIDERS.join(", ")}.`);
@@ -211,34 +255,61 @@ async function gatewayStatus(noNetwork = false) {
211
255
  }
212
256
  }
213
257
 
214
- async function printCockpit({ noNetwork = false } = {}) {
258
+ async function printCockpit({ noNetwork = false, json = false } = {}) {
215
259
  const gateway = await gatewayStatus(noNetwork);
216
260
  const passportConfigured = Boolean(config.passportId && config.passportSecret);
217
261
  const adminConfigured = Boolean(config.apiKey);
262
+ const dashboard = dashboardStatusLabel(gateway, noNetwork);
263
+ const app = appRootLabel();
264
+ const configFile = configPathLabel(config.sources);
265
+
266
+ if (json) {
267
+ console.log(JSON.stringify({
268
+ version: CLI_VERSION,
269
+ gateway: { url: config.gateway, state: gateway.label, healthy: gateway.ok },
270
+ dashboard: { state: dashboard },
271
+ app: { state: app },
272
+ config: {
273
+ source: configFile,
274
+ provider: config.provider,
275
+ model: config.model,
276
+ passport_configured: passportConfigured,
277
+ control_api_key_configured: adminConfigured,
278
+ },
279
+ }, null, 2));
280
+ return;
281
+ }
218
282
 
219
283
  console.log(`${heading("PassControl")}\n`);
220
284
  console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`));
221
- console.log(formatLabel("Dashboard", dashboardStatusLabel(gateway, noNetwork)));
222
- console.log(formatLabel("App", appRootLabel()));
223
- console.log(formatLabel("Config", configPathLabel(config.sources)));
285
+ console.log(formatLabel("Dashboard", dashboard));
286
+ console.log(formatLabel("App", app));
287
+ console.log(formatLabel("Config", configFile));
224
288
  console.log(formatLabel("Provider", config.provider));
225
289
  console.log(formatLabel("Model", config.model));
226
290
  console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing"));
227
291
  console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing"));
228
292
  console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`)}\n`);
229
- console.log(heading("Next commands:"));
230
- console.log(` ${cliCommand("start")} start the local dashboard`);
231
- console.log(` ${cliCommand("stop")} stop the local dashboard`);
232
- console.log(` ${cliCommand("restart")} restart the local dashboard`);
233
- console.log(` ${cliCommand("local-logs --follow")} follow local dashboard logs`);
234
- console.log(` ${cliCommand("init")} configure this project`);
235
- console.log(` ${cliCommand('call "hi"')} test a governed model call`);
236
- console.log(` ${cliCommand("sidecar")} start the local agent bridge`);
237
- console.log(` ${cliCommand("agent list")} list agents`);
238
- console.log(` ${cliCommand("spend")} show fleet spend`);
239
- console.log(` ${cliCommand("env openhands")} print agent settings`);
240
- console.log(` ${cliCommand("doctor")} check setup`);
241
- console.log(` ${cliCommand("open")} open dashboard`);
293
+ const next = [];
294
+ if (config.sources.length === 0) {
295
+ next.push(["init", "configure this project"]);
296
+ }
297
+ if (gateway.ok === false) {
298
+ next.push(["start", "start the local control plane"]);
299
+ next.push(["doctor", "diagnose why the gateway is unavailable"]);
300
+ } else if (!passportConfigured) {
301
+ next.push(["agent create <name>", "issue a governed agent passport"]);
302
+ next.push(["open", "finish setup in the Control Tower"]);
303
+ } else {
304
+ next.push(['call "hi"', "test a governed model call"]);
305
+ next.push(["agent list", "inspect the configured fleet"]);
306
+ next.push(["open", "open the Control Tower"]);
307
+ }
308
+
309
+ console.log(heading("Next:"));
310
+ for (const [command, description] of next.slice(0, 3)) {
311
+ console.log(` ${cliCommand(command).padEnd(34)} ${description}`);
312
+ }
242
313
  }
243
314
 
244
315
  function appConfigDir(env = process.env) {
@@ -359,12 +430,28 @@ function checkDockerDaemon() {
359
430
  };
360
431
  }
361
432
  try {
362
- execFileSync("docker", ["info"], { stdio: "ignore" });
433
+ // Docker Desktop can leave its CLI socket present while the engine is
434
+ // wedged. A diagnostic command must report that state, not hang every
435
+ // onboarding/release check indefinitely — hence a bound.
436
+ //
437
+ // The bound is generous because the failure it must not cause is worse than
438
+ // the one it prevents. At 2s this reported "not running" about a daemon that
439
+ // was merely COLD: it failed the public repo's local-smoke CI job on a runner
440
+ // where Docker was available throughout, and it would tell a first-time user
441
+ // on a slow laptop to go start something already running. A wedged engine
442
+ // still gets caught; it just takes fifteen seconds to say so.
443
+ execFileSync("docker", ["info"], { stdio: "ignore", timeout: 15_000 });
363
444
  return { ok: true, message: "Docker daemon: running." };
364
- } catch {
445
+ } catch (error) {
446
+ // A timeout and a stopped daemon need different things from the reader, so
447
+ // they must not share a sentence. `execFileSync` surfaces the timeout kill as
448
+ // ETIMEDOUT, or as the signal it used when the platform reports no code.
449
+ const timedOut = error?.code === "ETIMEDOUT" || error?.signal === "SIGTERM";
365
450
  return {
366
451
  ok: false,
367
- message: "Docker daemon: not running. Fix: start Docker Desktop and wait for the engine to become ready.",
452
+ message: timedOut
453
+ ? "Docker daemon: did not respond within 15s. The engine may still be starting — wait and re-run. If it persists, Docker is wedged: restart Docker Desktop."
454
+ : "Docker daemon: not running. Fix: start Docker Desktop and wait for the engine to become ready.",
368
455
  };
369
456
  }
370
457
  }
@@ -1039,12 +1126,17 @@ async function initCommand(opts) {
1039
1126
  }
1040
1127
  }
1041
1128
 
1129
+ // Destination first, passport second. The signature this produces is the
1130
+ // passport proving itself and carries no audience, so handing it to the wrong
1131
+ // host is the whole compromise — see `requirePassportGateway`. Validating here
1132
+ // covers every minting caller, `doctor --deep` and `try` included.
1042
1133
  async function mintVisa(current = config) {
1134
+ const origin = requirePassportGateway(current);
1043
1135
  const { passportId, passportSecret } = requirePassport(current);
1044
1136
  const payloadObj = { passport_id: passportId, ts: Date.now(), nonce: crypto.randomUUID() };
1045
1137
  const payload = b64url(new TextEncoder().encode(JSON.stringify(payloadObj)));
1046
1138
  const signature = b64url(ed25519.sign(fromB64url(payload), fromB64url(passportSecret)));
1047
- const res = await fetch(`${current.gateway}/api/auth/challenge`, {
1139
+ const res = await fetch(`${origin}/api/auth/challenge`, {
1048
1140
  method: "POST",
1049
1141
  headers: { "content-type": "application/json" },
1050
1142
  body: JSON.stringify({ payload, signature }),
@@ -1109,15 +1201,19 @@ async function callCommand(rest, opts) {
1109
1201
  assertProvider(provider);
1110
1202
  const model = activeModel(provider, opts);
1111
1203
  const prompt = rest.join(" ") || process.env.PROMPT || "Say hello in exactly 3 words.";
1204
+ // Before `requirePassport`, and before the banner: this line used to print
1205
+ // `config.gateway` verbatim, so `https://admin:hunter2@host` put the password
1206
+ // on the terminal and into any log scraping it.
1207
+ const origin = requirePassportGateway(config);
1112
1208
  requirePassport(config);
1113
- step(`${provider}/${model} via ${config.gateway}`);
1209
+ step(`${provider}/${model} via ${origin}`);
1114
1210
  step(`prompt: ${prompt}\n`);
1115
1211
 
1116
1212
  const { visa, expires_in } = await mintVisa(config);
1117
1213
  ok(`minted visa (expires in ${expires_in ?? 300}s)`);
1118
1214
 
1119
1215
  const { path: proxyPath, body } = requestFor(provider, model, prompt);
1120
- const res = await fetch(`${config.gateway}/api/v1/${provider}/${proxyPath}`, {
1216
+ const res = await fetch(`${origin}/api/v1/${provider}/${proxyPath}`, {
1121
1217
  method: "POST",
1122
1218
  headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
1123
1219
  body: JSON.stringify(body),
@@ -1132,7 +1228,9 @@ async function callCommand(rest, opts) {
1132
1228
  // keyless `demo` provider, then arms the kill switch to show the same call
1133
1229
  // blocked. Everything is real (visa, scope, budget, kill) except the model.
1134
1230
  async function tryCommand() {
1135
- const gateway = config.gateway;
1231
+ // Covers the demo proxy call AND the kill-switch PUT below, which builds its
1232
+ // own control-plane URL rather than going through the guarded `api()`.
1233
+ const gateway = requirePassportGateway(config);
1136
1234
  const demo = { gateway, passportId: DEMO_PASSPORT_ID, passportSecret: DEMO_PASSPORT_SECRET };
1137
1235
 
1138
1236
  const demoCall = async () => {
@@ -1204,7 +1302,7 @@ async function tryCommand() {
1204
1302
  const json = await res.json().catch(() => ({}));
1205
1303
  const text = json?.choices?.[0]?.message?.content ?? JSON.stringify(json);
1206
1304
  const usage = json?.usage ?? {};
1207
- ok("Governed keyless call succeeded — the passport signed a visa, the gateway enforced scope + budget, and no key was needed:");
1305
+ ok("Governed keyless call succeeded — the passport signed the challenge, the gateway issued a short-lived visa and enforced scope + budget, and no key was needed:");
1208
1306
  console.log(`\n ${text}\n`);
1209
1307
  step(`tokens: ${usage.total_tokens ?? "?"} (prompt ${usage.prompt_tokens ?? "?"} + completion ${usage.completion_tokens ?? "?"})`);
1210
1308
 
@@ -1230,8 +1328,13 @@ async function tryCommand() {
1230
1328
  }
1231
1329
 
1232
1330
  async function api(method, pathPart, body) {
1331
+ // Destination first, key second — same order and same reason as the SDK's
1332
+ // ControlClient. `config.gateway` is whatever PASSCONTROL_GATEWAY said, and
1333
+ // this is the one place a long-lived fleet-wide `pc_` key goes on the wire, so
1334
+ // the URL is built from the validated origin rather than from that string.
1335
+ const origin = requireControlGateway(config);
1233
1336
  const apiKey = requireControlApiKey(config);
1234
- const res = await fetch(`${config.gateway}/api/control/v1${pathPart}`, {
1337
+ const res = await fetch(`${origin}/api/control/v1${pathPart}`, {
1235
1338
  method,
1236
1339
  headers: {
1237
1340
  authorization: `Bearer ${apiKey}`,
@@ -1278,15 +1381,15 @@ async function agentCommand(rest, opts) {
1278
1381
  switch (sub) {
1279
1382
  case "list": {
1280
1383
  const agents = await api("GET", "/agents");
1281
- console.table(
1282
- agents.map((a) => ({
1384
+ const rows = agents.map((a) => ({
1283
1385
  id: a.id,
1284
1386
  name: a.name,
1285
1387
  status: a.status,
1286
1388
  tokens: a.spent_tokens,
1287
1389
  usd: a.spent_microcents === undefined ? undefined : usd(a.spent_microcents),
1288
- }))
1289
- );
1390
+ }));
1391
+ if (opts.json) console.log(JSON.stringify(rows, null, 2));
1392
+ else console.table(rows);
1290
1393
  break;
1291
1394
  }
1292
1395
  case "create": {
@@ -1322,13 +1425,57 @@ async function agentCommand(rest, opts) {
1322
1425
  if (!args[0]) throw new Error("Usage: passcontrol agent revoke <id>");
1323
1426
  console.log(await api("DELETE", `/agents/${encodeURIComponent(args[0])}`));
1324
1427
  break;
1428
+ // Retire this agent's key and install a new one, keeping the agent — its id,
1429
+ // budgets, audit history and receipts all stay put.
1430
+ //
1431
+ // The keypair is generated HERE, on the operator's machine, and only the
1432
+ // PUBLIC half is sent. That is the product: the gateway has never held a
1433
+ // passport private key and this command must not be the first thing to
1434
+ // change that.
1435
+ case "rotate": {
1436
+ if (!args[0]) {
1437
+ throw new Error("Usage: passcontrol agent rotate <id> [--grace <seconds>]");
1438
+ }
1439
+ const grace = opts.grace === undefined ? undefined : Number(opts.grace);
1440
+ if (grace !== undefined && (!Number.isFinite(grace) || grace < 0)) {
1441
+ throw new Error("--grace must be a non-negative number of seconds.");
1442
+ }
1443
+ const priv = ed25519.utils.randomPrivateKey();
1444
+ const passportId = b64url(ed25519.getPublicKey(priv));
1445
+ const result = await api("POST", `/agents/${encodeURIComponent(args[0])}/rotate`, {
1446
+ passportPubkey: passportId,
1447
+ ...(grace === undefined ? {} : { graceSeconds: grace }),
1448
+ });
1449
+
1450
+ ok(`rotated agent ${args[0]}`);
1451
+ // Printed BEFORE the deadline, and never written to a file. A rotation
1452
+ // that silently overwrote .passcontrol would destroy the only copy of the
1453
+ // key that is still working — mid-window, which is the outage the window
1454
+ // exists to prevent. The operator moves it deliberately.
1455
+ step("Store these - the secret is shown once and is the agent's new passport:");
1456
+ console.log(` PASSPORT_ID=${passportId}`);
1457
+ console.log(` PASSPORT_SECRET=${b64url(priv)}`);
1458
+ const until = result?.previous_valid_until;
1459
+ step(
1460
+ until
1461
+ ? `The OLD key keeps working until ${until}. Both keys authenticate until then — deploy the new one before it passes.`
1462
+ : "The old key stops working immediately."
1463
+ );
1464
+ break;
1465
+ }
1325
1466
  default:
1326
- throw new Error("Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>");
1467
+ throw new Error(
1468
+ "Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
1469
+ );
1327
1470
  }
1328
1471
  }
1329
1472
 
1330
- async function spendCommand() {
1473
+ async function spendCommand(opts = {}) {
1331
1474
  const data = await api("GET", "/spend");
1475
+ if (opts.json) {
1476
+ console.log(JSON.stringify(data, null, 2));
1477
+ return;
1478
+ }
1332
1479
  console.log(`fleet: ${data.fleet.spent_tokens} tokens · ${usd(data.fleet.spent_microcents)}`);
1333
1480
  console.table(
1334
1481
  data.agents.map((agent) => ({
@@ -1342,6 +1489,10 @@ async function spendCommand() {
1342
1489
 
1343
1490
  async function auditCommand(opts) {
1344
1491
  const events = await api("GET", controlPath("/audit", { limit: safeLimit(opts.limit) }));
1492
+ if (opts.json) {
1493
+ console.log(JSON.stringify(events, null, 2));
1494
+ return;
1495
+ }
1345
1496
  console.table(
1346
1497
  events.map((event) => ({
1347
1498
  at: event.created_at,
@@ -1361,6 +1512,10 @@ async function logsCommand(opts) {
1361
1512
  status: opts.status,
1362
1513
  })
1363
1514
  );
1515
+ if (opts.json) {
1516
+ console.log(JSON.stringify(rows, null, 2));
1517
+ return;
1518
+ }
1364
1519
  console.table(
1365
1520
  rows.map((row) => {
1366
1521
  const input = typeof row.input_tokens === "number" && Number.isFinite(row.input_tokens)
@@ -1398,13 +1553,32 @@ async function sidecarCommand(rest, opts) {
1398
1553
  return;
1399
1554
  }
1400
1555
 
1556
+ // Validate before the passport is read and before the listener binds: the
1557
+ // sidecar mints on demand for the lifetime of the process, so a bad
1558
+ // destination has to be refused at start, not at the first proxied request.
1559
+ const gateway = requirePassportGateway(config);
1401
1560
  const { passportId, passportSecret } = requirePassport(config);
1402
1561
  startSidecar({
1403
- gateway: config.gateway,
1562
+ gateway,
1404
1563
  passportId,
1405
1564
  passportSecret,
1406
- port: Number(opts.port ?? process.env.SIDECAR_PORT ?? 8788),
1565
+ port: sidecarPort(opts),
1407
1566
  host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
1567
+ // Named on the command line, never inferred. A sidecar reachable off-host
1568
+ // mints visas for whoever connects, so widening the bind is a decision the
1569
+ // operator states rather than one a config value makes quietly.
1570
+ allowNonLoopback: Boolean(opts.allowNonLoopback),
1571
+ // Hosts the agent may CONNECT-tunnel to, beyond the gateway itself. Provider
1572
+ // hosts are never eligible — see cli/proxy-policy.mjs.
1573
+ //
1574
+ // `operatorEnv`, not `process.env`, for the same reason `allowNonLoopback`
1575
+ // above takes no environment fallback at all: this is an egress control. A
1576
+ // `.passcontrol` that travels with a cloned repository was able to add tunnel
1577
+ // destinations to a sidecar started with no flags, and say nothing about it.
1578
+ allowConnectHosts: String(opts.allowConnect ?? operatorEnv("SIDECAR_ALLOW_CONNECT") ?? "")
1579
+ .split(",")
1580
+ .map((entry) => entry.trim())
1581
+ .filter(Boolean),
1408
1582
  refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
1409
1583
  });
1410
1584
 
@@ -1415,21 +1589,31 @@ async function sidecarCommand(rest, opts) {
1415
1589
  }
1416
1590
 
1417
1591
  async function mcpCommand() {
1592
+ const gateway = requirePassportGateway(config);
1418
1593
  const { passportId, passportSecret } = requirePassport(config);
1419
1594
  const { startMcpServer } = await import("../cli/mcp/server.mjs");
1420
- await startMcpServer({ gateway: config.gateway, passportId, passportSecret });
1595
+ await startMcpServer({ gateway, passportId, passportSecret });
1596
+ }
1597
+
1598
+ function sidecarPort(opts = {}) {
1599
+ const port = Number(opts.port ?? process.env.SIDECAR_PORT ?? 8788);
1600
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
1601
+ throw new Error("--port must be an integer from 1 to 65535.");
1602
+ }
1603
+ return port;
1421
1604
  }
1422
1605
 
1423
1606
  function sidecarBaseUrl(opts = {}) {
1424
1607
  const provider = String(opts.provider || config.provider);
1425
1608
  assertProvider(provider);
1426
1609
  const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
1427
- const port = Number(opts.port ?? process.env.SIDECAR_PORT ?? 8788);
1610
+ const port = sidecarPort(opts);
1428
1611
  return {
1429
1612
  provider,
1430
1613
  model: activeModel(provider, opts),
1431
1614
  apiKey: "passcontrol",
1432
1615
  baseUrl: `http://${host}:${port}/api/v1/${provider}`,
1616
+ port,
1433
1617
  };
1434
1618
  }
1435
1619
 
@@ -1479,9 +1663,11 @@ function printAgentPreset(name = "generic", opts = {}) {
1479
1663
  return;
1480
1664
  }
1481
1665
 
1482
- const { provider, model, apiKey, baseUrl } = sidecarBaseUrl(opts);
1666
+ const { provider, model, apiKey, baseUrl, port } = sidecarBaseUrl(opts);
1483
1667
  const modelWithProvider = `${provider}/${model}`;
1484
- const sidecarStart = opts.port ? cliCommand(`sidecar --port ${opts.port}`) : cliCommand("sidecar");
1668
+ const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
1669
+ ? cliCommand(`sidecar --port ${port}`)
1670
+ : cliCommand("sidecar");
1485
1671
 
1486
1672
  console.log(`# Start the bridge first: ${sidecarStart}`);
1487
1673
 
@@ -1497,6 +1683,16 @@ function printAgentPreset(name = "generic", opts = {}) {
1497
1683
  }
1498
1684
 
1499
1685
  switch (preset) {
1686
+ case "hermes":
1687
+ console.log("# Hermes Agent custom provider (verified against Hermes 0.18.2):");
1688
+ console.log("# Merge this model block into ~/.hermes/config.yaml:");
1689
+ console.log("model:");
1690
+ console.log(` default: ${JSON.stringify(model)}`);
1691
+ console.log(" provider: custom");
1692
+ console.log(` base_url: ${JSON.stringify(`${baseUrl}/v1`)}`);
1693
+ console.log(` api_key: ${JSON.stringify(apiKey)}`);
1694
+ console.log("# The placeholder key is stripped by the sidecar. Keep `passcontrol sidecar` running.");
1695
+ break;
1500
1696
  case "openhands":
1501
1697
  console.log("# OpenHands / LiteLLM-compatible starting point:");
1502
1698
  printExports([
@@ -1809,7 +2005,8 @@ async function main() {
1809
2005
  const [command, ...commandRest] = rest;
1810
2006
 
1811
2007
  if (opts.help || command === "help") {
1812
- console.log(usage());
2008
+ const target = command === "help" ? commandRest[0] : command;
2009
+ console.log(target === "agent" || target === "fleet" ? agentUsage() : usage());
1813
2010
  return;
1814
2011
  }
1815
2012
  if (opts.version || command === "version") {
@@ -1820,7 +2017,7 @@ async function main() {
1820
2017
  switch (command) {
1821
2018
  case undefined:
1822
2019
  case "status":
1823
- await printCockpit({ noNetwork: Boolean(opts.noNetwork) });
2020
+ await printCockpit({ noNetwork: Boolean(opts.noNetwork), json: Boolean(opts.json) });
1824
2021
  break;
1825
2022
  case "init":
1826
2023
  await initCommand(opts);
@@ -1872,7 +2069,7 @@ async function main() {
1872
2069
  await agentCommand(commandRest, opts);
1873
2070
  break;
1874
2071
  case "spend":
1875
- await spendCommand();
2072
+ await spendCommand(opts);
1876
2073
  break;
1877
2074
  case "audit":
1878
2075
  await auditCommand(opts);