passcontrol 1.4.0 → 1.5.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.
- package/LICENSE +3 -1
- package/README.md +10 -1
- package/bin/passcontrol.mjs +266 -8
- package/cli/budget-format.mjs +37 -0
- package/cli/claude-code.mjs +179 -0
- package/cli/client-events-upload.mjs +212 -0
- package/cli/config.mjs +35 -1
- package/cli/declared-session.mjs +32 -4
- package/cli/delegation.d.mts +60 -0
- package/cli/delegation.mjs +192 -0
- package/cli/menu.mjs +4 -0
- package/cli/otlp-logs.mjs +96 -0
- package/cli/profiles.mjs +92 -0
- package/cli/protocols.mjs +3 -1
- package/cli/sidecar.mjs +441 -21
- package/cli/statusline.mjs +223 -1
- package/cli/subscription-gate.mjs +213 -0
- package/cli/tool-gate.mjs +152 -0
- package/cli/tool-rules.d.mts +28 -0
- package/cli/tool-rules.mjs +206 -0
- package/cli/usage-window.mjs +66 -0
- package/cli/visa-client.mjs +5 -1
- package/cli/watch-feed.mjs +345 -0
- package/cli/watch.mjs +640 -0
- package/package.json +1 -1
- package/sdk/index.d.ts +2 -1
- package/sdk/index.js +3 -0
- package/sdk/passcontrol.d.ts +46 -0
- package/sdk/passcontrol.js +47 -2
- package/sdk/verify.d.ts +7 -0
package/LICENSE
CHANGED
|
@@ -8,7 +8,9 @@ License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
|
|
|
8
8
|
Parameters
|
|
9
9
|
|
|
10
10
|
Licensor: Kristiyan Ivanov, operating under the Vertias name
|
|
11
|
-
Licensed Work: PassControl
|
|
11
|
+
Licensed Work: PassControl, excluding the plugins/passcontrol/ directory,
|
|
12
|
+
which is licensed under the MIT License (see the
|
|
13
|
+
LICENSE file in that directory).
|
|
12
14
|
The Licensed Work is © 2026 Kristiyan Ivanov.
|
|
13
15
|
Additional Use Grant: You may make production use of the Licensed Work, provided
|
|
14
16
|
that you do not offer the Licensed Work to third parties as
|
package/README.md
CHANGED
|
@@ -19,7 +19,8 @@ not passport-signed. Both go through gateway controls.
|
|
|
19
19
|
|
|
20
20
|
Built by one developer under [Vertias](https://vertias.eu). Early software, **not
|
|
21
21
|
independently audited**. Start with a non-critical provider key. Source-available under
|
|
22
|
-
[BSL 1.1](./LICENSE)
|
|
22
|
+
[BSL 1.1](./LICENSE), except the Claude Code plugin in
|
|
23
|
+
[`plugins/passcontrol/`](https://github.com/Vertias3u/PassControl/tree/main/plugins/passcontrol), which is MIT.
|
|
23
24
|
|
|
24
25
|
## Cloud
|
|
25
26
|
|
|
@@ -129,6 +130,7 @@ its scope and suitable budgets. Choose by what your client supports:
|
|
|
129
130
|
| Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
|
|
130
131
|
| Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
|
|
131
132
|
| MCP client | `passcontrol mcp`; configure as below |
|
|
133
|
+
| Coding agent | [Claude Code](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/claude-code.md), [Codex](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/codex.md), [OpenRouter](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/openrouter.md), [Ollama](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/ollama.md) |
|
|
132
134
|
|
|
133
135
|
Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
|
|
134
136
|
point at loopback with a provider path (for example `http://127.0.0.1:8788/api/v1/anthropic`) and the sidecar forwards to the gateway.
|
|
@@ -161,6 +163,13 @@ API key. Treat access to that local listener as access to the configured agent.
|
|
|
161
163
|
not a sandbox against other processes running as you. Its provider CONNECT requests are
|
|
162
164
|
refused; use base URLs rather than TLS interception.
|
|
163
165
|
|
|
166
|
+
To see each call as it happens, run `passcontrol watch` beside the agent (`--port` for a
|
|
167
|
+
sidecar that is not on 8788). It is a read-only, full-screen board: one row per call the
|
|
168
|
+
sidecar relays, with its time, declared session and sub-agent, model, BOARDED or DENIED
|
|
169
|
+
(with the gateway's refusal code), and latency, under the agent's budget. It reads a feed
|
|
170
|
+
on the sidecar's own loopback port, held in memory and never written to disk. A call that
|
|
171
|
+
does not go through that sidecar is not on it, and the board cannot stop anything.
|
|
172
|
+
|
|
164
173
|
Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; service presets: `github`, `telegram`, `brave`, `notion`, `discord`; coding agent: `codex`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
165
174
|
supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
166
175
|
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -90,13 +90,26 @@ import {
|
|
|
90
90
|
import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
|
|
91
91
|
import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
|
|
92
92
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
93
|
+
import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
|
|
93
94
|
import {
|
|
94
95
|
claudeCodeEnv,
|
|
95
96
|
claudeCodeSettingsPath,
|
|
96
97
|
removeClaudeCodeSettings,
|
|
98
|
+
removeClaudeCodeSubscription,
|
|
99
|
+
subscriptionEnv,
|
|
100
|
+
subscriptionHooks,
|
|
97
101
|
writeClaudeCodeSettings,
|
|
102
|
+
writeClaudeCodeSubscription,
|
|
98
103
|
} from "../cli/claude-code.mjs";
|
|
99
|
-
import {
|
|
104
|
+
import {
|
|
105
|
+
notInPathText,
|
|
106
|
+
readStatusInput,
|
|
107
|
+
sidecarFromBaseUrl,
|
|
108
|
+
statusPanelText,
|
|
109
|
+
statuslineText,
|
|
110
|
+
statuslineWithWindow,
|
|
111
|
+
} from "../cli/statusline.mjs";
|
|
112
|
+
import { runWatch } from "../cli/watch.mjs";
|
|
100
113
|
import { CODEX_PROFILE, codexProfilePath, codexProfileToml, codexStoresApiKey, removeCodexProfile, writeCodexProfile } from "../cli/codex.mjs";
|
|
101
114
|
import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
|
|
102
115
|
import { loginCommand } from "../cli/login.mjs";
|
|
@@ -206,8 +219,10 @@ ${heading("Quick start")}
|
|
|
206
219
|
${cmd} login [--project] sign in through your browser and set this machine up
|
|
207
220
|
${cmd} call "hi" mint a visa and make a governed model call
|
|
208
221
|
${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
|
|
209
|
-
${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal]
|
|
222
|
+
${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal] [--no-report-calls]
|
|
210
223
|
passport identity for any tool that takes an api_key
|
|
224
|
+
${cmd} sidecar --profile <name> | --profiles a,b
|
|
225
|
+
run a coding tool's own sidecar (or several, one process)
|
|
211
226
|
|
|
212
227
|
${heading("Operate")}
|
|
213
228
|
${cmd} status [--no-network] [--json]
|
|
@@ -223,6 +238,7 @@ ${heading("Operate")}
|
|
|
223
238
|
|
|
224
239
|
${heading("Manage")}
|
|
225
240
|
${cmd} agent list [--json] list agents
|
|
241
|
+
${cmd} profile list [--json] show the profiles: one identity per coding tool
|
|
226
242
|
${cmd} agent create <name> [--write]
|
|
227
243
|
create an agent passport (--write saves it here)
|
|
228
244
|
${cmd} agent rotate <id> [--grace <seconds>]
|
|
@@ -230,6 +246,10 @@ ${heading("Manage")}
|
|
|
230
246
|
${cmd} agent suspend <id> suspend an agent
|
|
231
247
|
${cmd} agent resume <id> resume an agent
|
|
232
248
|
${cmd} agent revoke <id> permanently revoke an agent
|
|
249
|
+
${cmd} agent delegations <id> [--json]
|
|
250
|
+
list the delegations its workers have used
|
|
251
|
+
${cmd} agent revoke-delegation <id> <jti>|--all
|
|
252
|
+
permanently revoke one delegation, or all before now
|
|
233
253
|
${cmd} spend [--json] show fleet and per-agent spend
|
|
234
254
|
${cmd} audit [--limit 20] [--json]
|
|
235
255
|
show operator audit history
|
|
@@ -240,8 +260,10 @@ ${heading("Manage")}
|
|
|
240
260
|
${cmd} sessions [--agent ID] [--limit 20] [--json]
|
|
241
261
|
list Claude Code / Codex sessions (declared by the client)
|
|
242
262
|
${cmd} seal <session> --agent ID [--out FILE]
|
|
243
|
-
${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
|
|
244
263
|
sign one session; save the seal and its receipts
|
|
264
|
+
${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
|
|
265
|
+
${cmd} statusline --panel [--session <id>] the longer view the Claude Code plugin's /passcontrol shows
|
|
266
|
+
${cmd} watch [--port 8788] a live board of each call the sidecar relays (read-only)
|
|
245
267
|
${cmd} kill on|off toggle the tenant kill switch
|
|
246
268
|
${cmd} export [--out FILE] save a workspace configuration snapshot
|
|
247
269
|
${cmd} import <file> [--confirm IMPORT]
|
|
@@ -249,8 +271,10 @@ ${heading("Manage")}
|
|
|
249
271
|
|
|
250
272
|
${heading("Integrate")}
|
|
251
273
|
${cmd} env [integration] print settings without writing anything
|
|
252
|
-
${cmd} configure <integration> [--write] [--force]
|
|
274
|
+
${cmd} configure <integration> [--write] [--force] [--dedicated]
|
|
253
275
|
preview or write integration config
|
|
276
|
+
${cmd} configure claude-code --subscription [--write|--remove]
|
|
277
|
+
a Pro/Max login: stops, calls, usage window
|
|
254
278
|
integrations: ${integrationChoices()}
|
|
255
279
|
|
|
256
280
|
${heading("Trust")}
|
|
@@ -302,6 +326,8 @@ ${heading("Usage:")}
|
|
|
302
326
|
${cmd} agent suspend <id>
|
|
303
327
|
${cmd} agent resume <id>
|
|
304
328
|
${cmd} agent revoke <id>
|
|
329
|
+
${cmd} agent delegations <id> [--json]
|
|
330
|
+
${cmd} agent revoke-delegation <id> <jti>|--all
|
|
305
331
|
|
|
306
332
|
${heading("Examples")}
|
|
307
333
|
${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
|
|
@@ -373,6 +399,7 @@ async function printCockpit({ noNetwork = false, json = false } = {}) {
|
|
|
373
399
|
app: { state: app },
|
|
374
400
|
config: {
|
|
375
401
|
source: configFile,
|
|
402
|
+
profile: config.profile,
|
|
376
403
|
provider: config.provider,
|
|
377
404
|
model: config.model,
|
|
378
405
|
passport_configured: passportConfigured,
|
|
@@ -2273,9 +2300,66 @@ async function agentCommand(rest, opts) {
|
|
|
2273
2300
|
step("passport instead, and leaves this one working everywhere it already runs.");
|
|
2274
2301
|
break;
|
|
2275
2302
|
}
|
|
2303
|
+
// An agent's signed delegations to its workers (Bet D). A delegation is made
|
|
2304
|
+
// offline, so the gateway knows a link only once a worker has exchanged it; the
|
|
2305
|
+
// listing says so, and --all is the tool that reaches the ones never seen.
|
|
2306
|
+
case "delegations": {
|
|
2307
|
+
if (!args[0]) throw new Error("Usage: passcontrol agent delegations <agent-id> [--json]");
|
|
2308
|
+
const rows = await api("GET", `/agents/${encodeURIComponent(args[0])}/delegations`);
|
|
2309
|
+
if (opts.json) {
|
|
2310
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
2311
|
+
break;
|
|
2312
|
+
}
|
|
2313
|
+
step("Only delegations a worker has used appear here. A delegation is signed offline, so the");
|
|
2314
|
+
step("gateway learns of it at its first exchange; `revoke-delegation --all` also reaches unseen ones.");
|
|
2315
|
+
if (!Array.isArray(rows) || rows.length === 0) {
|
|
2316
|
+
step("No worker has used a delegation from this agent yet.");
|
|
2317
|
+
break;
|
|
2318
|
+
}
|
|
2319
|
+
// Server text reaches a terminal: keep it to printable ASCII.
|
|
2320
|
+
const printable = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 64);
|
|
2321
|
+
const now = Date.now();
|
|
2322
|
+
console.table(
|
|
2323
|
+
rows.map((d) => ({
|
|
2324
|
+
jti: printable(d.jti),
|
|
2325
|
+
depth: d.depth,
|
|
2326
|
+
status: d.revoked ? "revoked" : Date.parse(d.expires_at) <= now ? "expired" : "active",
|
|
2327
|
+
worker: `${printable(d.worker_key).slice(0, 12)}…`,
|
|
2328
|
+
cap: usd(d.cap_microcents),
|
|
2329
|
+
models: Array.isArray(d.scope)
|
|
2330
|
+
? d.scope.map((s) => `${printable(s?.provider)}:${(Array.isArray(s?.models) ? s.models : []).map(printable).join("|")}`).join(", ")
|
|
2331
|
+
: "",
|
|
2332
|
+
expires: printable(d.expires_at).slice(0, 19),
|
|
2333
|
+
"first used": printable(d.first_exchanged_at).slice(0, 19),
|
|
2334
|
+
}))
|
|
2335
|
+
);
|
|
2336
|
+
break;
|
|
2337
|
+
}
|
|
2338
|
+
case "revoke-delegation": {
|
|
2339
|
+
const usage = "Usage: passcontrol agent revoke-delegation <agent-id> <jti>|--all";
|
|
2340
|
+
const [agentId, jti] = args;
|
|
2341
|
+
const all = opts.all === true;
|
|
2342
|
+
if (!agentId || all === Boolean(jti)) throw new Error(usage);
|
|
2343
|
+
const result = await api(
|
|
2344
|
+
"POST",
|
|
2345
|
+
`/agents/${encodeURIComponent(agentId)}/delegations/revoke`,
|
|
2346
|
+
all ? { all: true } : { jti }
|
|
2347
|
+
);
|
|
2348
|
+
ok(
|
|
2349
|
+
all
|
|
2350
|
+
? `revoked every delegation agent ${agentId} issued before now, seen or not`
|
|
2351
|
+
: `revoked delegation ${jti} and every delegation under it`
|
|
2352
|
+
);
|
|
2353
|
+
step("This is permanent. To let a worker go on, the agent delegates to it again.");
|
|
2354
|
+
if (result?.immediate === false) {
|
|
2355
|
+
step("Recorded, but the gateway's fast copy could not be written: a worker holding a current");
|
|
2356
|
+
step("visa can keep calling until that visa expires (5 minutes by default).");
|
|
2357
|
+
}
|
|
2358
|
+
break;
|
|
2359
|
+
}
|
|
2276
2360
|
default:
|
|
2277
2361
|
throw new Error(
|
|
2278
|
-
"Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
|
|
2362
|
+
"Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]|delegations <id>|revoke-delegation <id> <jti>|--all"
|
|
2279
2363
|
);
|
|
2280
2364
|
}
|
|
2281
2365
|
}
|
|
@@ -2368,6 +2452,32 @@ async function sidecarCommand(rest, opts) {
|
|
|
2368
2452
|
// sidecar mints on demand for the lifetime of the process, so a bad
|
|
2369
2453
|
// destination has to be refused at start, not at the first proxied request.
|
|
2370
2454
|
const gateway = requirePassportGateway(config);
|
|
2455
|
+
if (opts.profiles) {
|
|
2456
|
+
// Several identities, one process: one listener per profile, each with its own
|
|
2457
|
+
// passport, visa and journal (candidate 4). One terminal, one Ctrl-C.
|
|
2458
|
+
const names = String(opts.profiles).split(",").map((n) => n.trim()).filter(Boolean);
|
|
2459
|
+
for (const name of names) {
|
|
2460
|
+
const values = readProfile(name);
|
|
2461
|
+
if (!values?.PASSPORT_ID || !values?.PASSPORT_SECRET) {
|
|
2462
|
+
throw new Error(`Profile ${name} has no passport. Create it with ${cliCommand(`configure ${name} --dedicated --write`)}.`);
|
|
2463
|
+
}
|
|
2464
|
+
step(`Profile ${name}:`);
|
|
2465
|
+
startSidecar({
|
|
2466
|
+
gateway,
|
|
2467
|
+
passportId: values.PASSPORT_ID,
|
|
2468
|
+
passportSecret: values.PASSPORT_SECRET,
|
|
2469
|
+
keyStorage: null,
|
|
2470
|
+
port: sidecarPort({ port: values.SIDECAR_PORT }),
|
|
2471
|
+
host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
|
|
2472
|
+
allowNonLoopback: Boolean(opts.allowNonLoopback),
|
|
2473
|
+
allowConnectHosts: [],
|
|
2474
|
+
refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
|
|
2475
|
+
noJournal: opts.journal === false || Boolean(opts.noJournal),
|
|
2476
|
+
reportCalls: !(opts.reportCalls === false || Boolean(opts.noReportCalls)),
|
|
2477
|
+
});
|
|
2478
|
+
}
|
|
2479
|
+
return;
|
|
2480
|
+
}
|
|
2371
2481
|
const { passportId, passportSecret, keyStorage } = requirePassport(config);
|
|
2372
2482
|
startSidecar({
|
|
2373
2483
|
gateway,
|
|
@@ -2397,6 +2507,9 @@ async function sidecarCommand(rest, opts) {
|
|
|
2397
2507
|
// A flag only, like --allow-non-loopback: whether this machine keeps a record
|
|
2398
2508
|
// is the operator's to state, not a config file's.
|
|
2399
2509
|
noJournal: opts.journal === false || Boolean(opts.noJournal),
|
|
2510
|
+
// Subscription mode: the calls Claude Code reports go to the agent's page. On
|
|
2511
|
+
// unless the flag says off, like the journal.
|
|
2512
|
+
reportCalls: !(opts.reportCalls === false || Boolean(opts.noReportCalls)),
|
|
2400
2513
|
});
|
|
2401
2514
|
|
|
2402
2515
|
if (opts.for) {
|
|
@@ -2427,8 +2540,26 @@ function sidecarPort(opts = {}) {
|
|
|
2427
2540
|
async function statuslineCommand(opts) {
|
|
2428
2541
|
try {
|
|
2429
2542
|
const port = sidecarPort(opts);
|
|
2543
|
+
// `--panel`: the several-line view `/passcontrol` shows in Claude Code (F3).
|
|
2544
|
+
// Without --port, the sidecar Claude Code's own ANTHROPIC_BASE_URL names.
|
|
2545
|
+
if (opts.panel) {
|
|
2546
|
+
const route = opts.port === undefined ? sidecarFromBaseUrl(process.env.ANTHROPIC_BASE_URL) : null;
|
|
2547
|
+
if (route?.remote) return notInPathText(route.remote);
|
|
2548
|
+
// Subscription mode (cli/subscription-gate.mjs): no ANTHROPIC_BASE_URL, since
|
|
2549
|
+
// the calls go to Anthropic directly; `configure claude-code --subscription`
|
|
2550
|
+
// names the sidecar the hooks and telemetry use instead.
|
|
2551
|
+
const reported = !route && opts.port === undefined ? sidecarFromBaseUrl(process.env.PASSCONTROL_SIDECAR_URL) : null;
|
|
2552
|
+
return await statusPanelText({
|
|
2553
|
+
port: route?.port ?? reported?.port ?? port,
|
|
2554
|
+
gateway: config.gateway,
|
|
2555
|
+
session: typeof opts.session === "string" ? opts.session : null,
|
|
2556
|
+
subscription: Boolean(reported?.port),
|
|
2557
|
+
});
|
|
2558
|
+
}
|
|
2430
2559
|
const cacheFile = path.join(path.dirname(globalConfigPath()), `statusline-${port}.json`);
|
|
2431
|
-
|
|
2560
|
+
// On a Pro/Max login Claude Code adds the usage window to its input (cli/usage-window.mjs).
|
|
2561
|
+
const input = await readStatusInput();
|
|
2562
|
+
return await statuslineWithWindow({ input, port, budgetLine: () => statuslineText({ port, cacheFile }) });
|
|
2432
2563
|
} catch (error) {
|
|
2433
2564
|
return `PassControl · ${error instanceof Error && /--port/.test(error.message) ? "bad --port" : "unavailable"}`;
|
|
2434
2565
|
}
|
|
@@ -2482,7 +2613,9 @@ function passControlMcpEntry() {
|
|
|
2482
2613
|
}
|
|
2483
2614
|
|
|
2484
2615
|
function printMcpPreset(integration, opts = {}) {
|
|
2485
|
-
|
|
2616
|
+
// Claude Code's lines only point it at the sidecar, which holds the passport (as in
|
|
2617
|
+
// configureMcpClient); the MCP clients below launch `passcontrol mcp`, which needs it.
|
|
2618
|
+
if (integration !== "claude-code") requireGlobalMcpPassport();
|
|
2486
2619
|
if (integration === "claude-code") {
|
|
2487
2620
|
const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
|
|
2488
2621
|
console.log("# Route Claude Code's model calls through the sidecar (start it first):");
|
|
@@ -2642,6 +2775,7 @@ function aiderConfig(opts = {}) {
|
|
|
2642
2775
|
* Claude Code owns.
|
|
2643
2776
|
*/
|
|
2644
2777
|
function configureClaudeCode(opts = {}) {
|
|
2778
|
+
if (opts.subscription) return configureClaudeCodeSubscription(opts);
|
|
2645
2779
|
const scope = opts.global ? "user" : "project";
|
|
2646
2780
|
const target = claudeCodeSettingsPath({ scope });
|
|
2647
2781
|
if (opts.remove) {
|
|
@@ -2684,6 +2818,52 @@ function configureClaudeCode(opts = {}) {
|
|
|
2684
2818
|
step(`To undo: ${cliCommand(`configure claude-code --remove${scope === "user" ? " --global" : ""}`)}`);
|
|
2685
2819
|
}
|
|
2686
2820
|
|
|
2821
|
+
/**
|
|
2822
|
+
* Subscription mode (cli/claude-code.mjs): a Claude
|
|
2823
|
+
* Pro/Max login keeps talking to Anthropic directly. PassControl is told about each
|
|
2824
|
+
* call, asked before each prompt and tool, and shown the usage window. Always the
|
|
2825
|
+
* user settings: Claude Code ignores telemetry settings in a project's file.
|
|
2826
|
+
*/
|
|
2827
|
+
function configureClaudeCodeSubscription(opts = {}) {
|
|
2828
|
+
const target = claudeCodeSettingsPath({ scope: "user" });
|
|
2829
|
+
const port = sidecarPort(opts);
|
|
2830
|
+
if (opts.remove) {
|
|
2831
|
+
const result = removeClaudeCodeSubscription({ target });
|
|
2832
|
+
if (result.changed) ok(`removed PassControl's subscription mode from ${target}`);
|
|
2833
|
+
else step(`${target} has no PassControl subscription settings; nothing to remove.`);
|
|
2834
|
+
return;
|
|
2835
|
+
}
|
|
2836
|
+
const preview = { env: subscriptionEnv(port), hooks: subscriptionHooks(port), statusLine: { type: "command", command: statusLineSettingsCommand(port) } };
|
|
2837
|
+
console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
|
|
2838
|
+
if (!opts.write) {
|
|
2839
|
+
step("Dry run only. Re-run with `--write` to merge these into your Claude Code user settings (anything of yours is kept).");
|
|
2840
|
+
} else {
|
|
2841
|
+
const result = writeClaudeCodeSubscription({ target, port, statusLineCommand: statusLineSettingsCommand(port), force: Boolean(opts.force) });
|
|
2842
|
+
if (!result.changed) ok(`${target} already has PassControl's subscription mode`);
|
|
2843
|
+
else {
|
|
2844
|
+
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
2845
|
+
ok(`wrote ${target}`);
|
|
2846
|
+
}
|
|
2847
|
+
if (result.statusLine?.existing) {
|
|
2848
|
+
warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is, so the usage window is not shown. To show it, have yours pipe its input to \`${statusLineSettingsCommand(port)}\`.`);
|
|
2849
|
+
}
|
|
2850
|
+
if (result.hookUrlsBlocked) {
|
|
2851
|
+
warn(`${target} sets allowedHttpHookUrls, which does not include http://127.0.0.1:${port}/_passcontrol/hook and its tool hook (…/_passcontrol/hook?t=600): Claude Code will not run them until you add both, for example http://127.0.0.1:${port}/_passcontrol/hook*.`);
|
|
2852
|
+
}
|
|
2853
|
+
if (result.routed) {
|
|
2854
|
+
warn(`${target} also routes Claude Code through the sidecar with PassControl's API key (ANTHROPIC_BASE_URL). Those sessions do not use your subscription. To use the subscription, run ${cliCommand("configure claude-code --remove --global")}.`);
|
|
2855
|
+
}
|
|
2856
|
+
}
|
|
2857
|
+
step(`Start the sidecar before Claude Code: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
|
|
2858
|
+
step("Your Pro/Max login stays between Claude Code and Anthropic. PassControl never sees it or sits in the path.");
|
|
2859
|
+
step("If the sidecar is not running, Claude Code still works: stops are not checked and calls are not shown until it is.");
|
|
2860
|
+
step(`Watch the calls: ${cliCommand("watch")}`);
|
|
2861
|
+
step(
|
|
2862
|
+
`The sidecar also uploads each reported call (model, session, tokens, time, API-equivalent cost; never your email or account ids) to the agent's dashboard page, marked as reported, not proxied. To keep them on this machine only: ${cliCommand("sidecar --no-report-calls")}`
|
|
2863
|
+
);
|
|
2864
|
+
step(`To undo: ${cliCommand("configure claude-code --subscription --remove")}`);
|
|
2865
|
+
}
|
|
2866
|
+
|
|
2687
2867
|
/**
|
|
2688
2868
|
* Codex speaks only OpenAI's Responses API, so its profile always points at the
|
|
2689
2869
|
* sidecar's OpenAI route. A model is written only when one is named with
|
|
@@ -2709,6 +2889,68 @@ function printCodexPreset(opts = {}) {
|
|
|
2709
2889
|
* Codex layers over its config when started with `--profile passcontrol`.
|
|
2710
2890
|
* `--remove` deletes that file, and only when PassControl wrote it.
|
|
2711
2891
|
*/
|
|
2892
|
+
// ── One identity per coding tool (candidate 4, plans/one-identity-per-tool.md) ──
|
|
2893
|
+
//
|
|
2894
|
+
// `configure <tool> --dedicated` gives Claude Code or Codex its OWN agent: its own
|
|
2895
|
+
// passport, budget, scope and kill switch, served by its own sidecar port, kept in
|
|
2896
|
+
// a named profile (cli/profiles.mjs). Re-running reuses the profile; it never
|
|
2897
|
+
// creates a second agent.
|
|
2898
|
+
async function prepareDedicatedProfile(tool, opts) {
|
|
2899
|
+
const port = TOOL_PROFILE_PORTS[tool];
|
|
2900
|
+
opts.port = port;
|
|
2901
|
+
const existing = readProfile(tool);
|
|
2902
|
+
if (existing?.PASSPORT_ID && existing?.PASSPORT_SECRET) {
|
|
2903
|
+
opts.port = Number(existing.SIDECAR_PORT || port);
|
|
2904
|
+
step(`Using the ${tool} profile's own agent (passport …${existing.PASSPORT_ID.slice(-8)}), sidecar port ${opts.port}.`);
|
|
2905
|
+
return;
|
|
2906
|
+
}
|
|
2907
|
+
const label = tool === "claude-code" ? "Claude Code" : "Codex";
|
|
2908
|
+
const provider = tool === "claude-code" ? "anthropic" : "openai";
|
|
2909
|
+
const name = `${label} @ ${os.hostname().split(".")[0] || "this machine"}`;
|
|
2910
|
+
if (!opts.write) {
|
|
2911
|
+
step(`With --write: creates the agent "${name}" with its own passport, saved in the ${tool} profile, served on sidecar port ${port}.`);
|
|
2912
|
+
return;
|
|
2913
|
+
}
|
|
2914
|
+
requireControlApiKey(config);
|
|
2915
|
+
// The keypair is made here and only the public half leaves, as in `agent create`.
|
|
2916
|
+
// The profile is written FIRST, so a created agent never exists without its key on
|
|
2917
|
+
// this machine; if creating it fails, the profile is removed again.
|
|
2918
|
+
const priv = ed25519.utils.randomPrivateKey();
|
|
2919
|
+
const passportId = b64url(ed25519.getPublicKey(priv));
|
|
2920
|
+
writeProfile(tool, { PASSPORT_ID: passportId, PASSPORT_SECRET: b64url(priv), PASSPORT_KEY_STORAGE: "", SIDECAR_PORT: String(port) });
|
|
2921
|
+
let created;
|
|
2922
|
+
try {
|
|
2923
|
+
created = await api("POST", "/agents", {
|
|
2924
|
+
name,
|
|
2925
|
+
passportPubkey: passportId,
|
|
2926
|
+
scopes: [{ provider, models: [defaultAllowedModelForProvider(provider)] }],
|
|
2927
|
+
});
|
|
2928
|
+
} catch (error) {
|
|
2929
|
+
fs.rmSync(profilePath(tool), { force: true });
|
|
2930
|
+
throw error;
|
|
2931
|
+
}
|
|
2932
|
+
ok(`created agent ${created.id} (${created.name}); its passport is in the ${tool} profile and was not printed`);
|
|
2933
|
+
}
|
|
2934
|
+
|
|
2935
|
+
function dedicatedSidecarHint(tool) {
|
|
2936
|
+
step(`Run its own sidecar: ${cliCommand(`sidecar --profile ${tool}`)}`);
|
|
2937
|
+
step(`Both coding tools at once, each as its own agent: ${cliCommand("sidecar --profiles claude-code,codex")}`);
|
|
2938
|
+
}
|
|
2939
|
+
|
|
2940
|
+
function profileCommand(rest, opts) {
|
|
2941
|
+
if (rest[0] !== "list") throw new Error("Usage: passcontrol profile list");
|
|
2942
|
+
const rows = listProfiles().map((p) => ({ profile: p.name, passport: p.passportId ? `…${p.passportId.slice(-8)}` : "none", port: p.port || "-" }));
|
|
2943
|
+
if (opts.json) {
|
|
2944
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
2945
|
+
return;
|
|
2946
|
+
}
|
|
2947
|
+
if (!rows.length) {
|
|
2948
|
+
step(`No profiles yet. Give a coding tool its own agent: ${cliCommand("configure claude-code --dedicated --write")}`);
|
|
2949
|
+
return;
|
|
2950
|
+
}
|
|
2951
|
+
for (const r of rows) console.log(`${r.profile.padEnd(20)} passport ${r.passport.padEnd(10)} port ${r.port}`);
|
|
2952
|
+
}
|
|
2953
|
+
|
|
2712
2954
|
function configureCodex(opts = {}) {
|
|
2713
2955
|
const target = codexProfilePath();
|
|
2714
2956
|
if (opts.remove) {
|
|
@@ -2739,11 +2981,13 @@ function configureCodex(opts = {}) {
|
|
|
2739
2981
|
}
|
|
2740
2982
|
|
|
2741
2983
|
function configureMcpClient(integration, opts = {}) {
|
|
2742
|
-
|
|
2984
|
+
// Claude Code's settings only point it at the sidecar, which holds the passport
|
|
2985
|
+
// itself; requiring one here also stopped `--remove` once the config was gone.
|
|
2743
2986
|
if (integration === "claude-code") {
|
|
2744
2987
|
configureClaudeCode(opts);
|
|
2745
2988
|
return;
|
|
2746
2989
|
}
|
|
2990
|
+
requireGlobalMcpPassport();
|
|
2747
2991
|
|
|
2748
2992
|
const target = mcpClientConfigPath(integration);
|
|
2749
2993
|
const entry = passControlMcpEntry();
|
|
@@ -2775,12 +3019,17 @@ async function configureCommand(rest, opts = {}) {
|
|
|
2775
3019
|
`Unknown integration "${integration}". Use one of: ${integrationChoices()}.`
|
|
2776
3020
|
);
|
|
2777
3021
|
}
|
|
3022
|
+
if (opts.dedicated && (integration === "claude-code" || integration === "codex")) {
|
|
3023
|
+
await prepareDedicatedProfile(integration, opts);
|
|
3024
|
+
}
|
|
2778
3025
|
if (integration === "codex") {
|
|
2779
3026
|
configureCodex(opts);
|
|
3027
|
+
if (opts.dedicated) dedicatedSidecarHint(integration);
|
|
2780
3028
|
return;
|
|
2781
3029
|
}
|
|
2782
3030
|
if (isMcpIntegration(integration)) {
|
|
2783
3031
|
configureMcpClient(integration, opts);
|
|
3032
|
+
if (opts.dedicated && integration === "claude-code") dedicatedSidecarHint(integration);
|
|
2784
3033
|
return;
|
|
2785
3034
|
}
|
|
2786
3035
|
if (!supportsWrite(integration)) {
|
|
@@ -4198,6 +4447,12 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
4198
4447
|
return;
|
|
4199
4448
|
}
|
|
4200
4449
|
|
|
4450
|
+
// Also before the update check: a full-screen board owns the terminal from its
|
|
4451
|
+
// first frame, and the check's cache would be the one file `watch` ever wrote.
|
|
4452
|
+
if (command === "watch" && !opts.help) {
|
|
4453
|
+
process.exit(await runWatch({ port: sidecarPort(opts) }));
|
|
4454
|
+
}
|
|
4455
|
+
|
|
4201
4456
|
// Started here and awaited at the very end, so the registry lookup overlaps
|
|
4202
4457
|
// the command instead of being tacked onto the exit. On anything that touches
|
|
4203
4458
|
// the network — which is most of this CLI — it costs nothing measurable, and
|
|
@@ -4299,6 +4554,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
4299
4554
|
" `passcontrol login` now does the same thing with YOUR agent rather than a\n" +
|
|
4300
4555
|
" shared demo one: a governed call and a signed receipt you can verify."
|
|
4301
4556
|
);
|
|
4557
|
+
case "profile":
|
|
4558
|
+
profileCommand(commandRest, opts);
|
|
4559
|
+
break;
|
|
4302
4560
|
case "sidecar":
|
|
4303
4561
|
await sidecarCommand(commandRest, opts);
|
|
4304
4562
|
break;
|
package/cli/budget-format.mjs
CHANGED
|
@@ -74,3 +74,40 @@ export function budgetLines(self) {
|
|
|
74
74
|
if (lines.length === 0) lines.push("No spending or token limit is set for this agent.");
|
|
75
75
|
return lines;
|
|
76
76
|
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Every limit as a [label, value] row, for the `/passcontrol` panel in Claude Code
|
|
80
|
+
* (`passcontrol statusline --panel`): "Today", "$0.42 of $10.00 · $9.58 left · resets in 7h".
|
|
81
|
+
*/
|
|
82
|
+
export function panelRows(self) {
|
|
83
|
+
const b = self?.budget ?? {};
|
|
84
|
+
const rows = [];
|
|
85
|
+
if (b.period && b.period.unknown) {
|
|
86
|
+
rows.push(["Limit", "could not be read right now"]);
|
|
87
|
+
} else if (b.period) {
|
|
88
|
+
const reset = resetsIn(b.period.resets_in_seconds);
|
|
89
|
+
rows.push([
|
|
90
|
+
PERIOD_LABEL[b.period.kind] ?? "This period",
|
|
91
|
+
`${formatUsd(b.period.used_microcents)} of ${formatUsd(b.period.limit_microcents)} · ${formatUsd(b.period.remaining_microcents)} left${reset ? ` · resets in ${reset}` : ""}`,
|
|
92
|
+
]);
|
|
93
|
+
}
|
|
94
|
+
if (b.cost) {
|
|
95
|
+
rows.push(["Lifetime", `${formatUsd(b.cost.used_microcents)} of ${formatUsd(b.cost.limit_microcents)} · ${formatUsd(b.cost.remaining_microcents)} left`]);
|
|
96
|
+
}
|
|
97
|
+
if (b.tokens) {
|
|
98
|
+
rows.push(["Tokens", `${formatTokens(b.tokens.used)} of ${formatTokens(b.tokens.limit)} · ${formatTokens(b.tokens.remaining)} left`]);
|
|
99
|
+
}
|
|
100
|
+
if (rows.length === 0) rows.push(["Limit", "none set"]);
|
|
101
|
+
return rows;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Whether a limit has nothing left, so the gateway refuses calls until it resets or is raised. */
|
|
105
|
+
export function limitReached(self) {
|
|
106
|
+
const b = self?.budget ?? {};
|
|
107
|
+
const spent = (left) => left !== null && left !== undefined && Number.isFinite(Number(left)) && Number(left) <= 0;
|
|
108
|
+
return Boolean(
|
|
109
|
+
(b.period && !b.period.unknown && spent(b.period.remaining_microcents)) ||
|
|
110
|
+
(b.cost && spent(b.cost.remaining_microcents)) ||
|
|
111
|
+
(b.tokens && spent(b.tokens.remaining))
|
|
112
|
+
);
|
|
113
|
+
}
|