passcontrol 1.5.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/bin/passcontrol.mjs +75 -4
- package/cli/claude-code.mjs +179 -0
- package/cli/client-events-upload.mjs +212 -0
- package/cli/otlp-logs.mjs +96 -0
- package/cli/sidecar.mjs +288 -5
- package/cli/statusline.mjs +105 -7
- 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/watch-feed.mjs +77 -7
- package/cli/watch.mjs +49 -10
- package/package.json +1 -1
package/cli/watch-feed.mjs
CHANGED
|
@@ -82,9 +82,12 @@ export function providerOf(path) {
|
|
|
82
82
|
return match ? held(PROVIDER, match[1]) : null;
|
|
83
83
|
}
|
|
84
84
|
|
|
85
|
-
/**
|
|
86
|
-
|
|
87
|
-
|
|
85
|
+
/**
|
|
86
|
+
* Gateway paths that are not model calls: the budget read the board and the status
|
|
87
|
+
* line poll, and the upload of calls a client reported (cli/client-events-upload.mjs).
|
|
88
|
+
*/
|
|
89
|
+
export function isNotACall(path) {
|
|
90
|
+
return /^\/api\/v1\/(self|client-events)(\?|$)/.test(String(path ?? ""));
|
|
88
91
|
}
|
|
89
92
|
|
|
90
93
|
/** Reads at most `limit` bytes of a (cloned) body, then cancels it. Never throws. */
|
|
@@ -117,7 +120,18 @@ function hostIsThisListener(hostHeader, port) {
|
|
|
117
120
|
return Boolean(match && LOOPBACK_NAMES.has(match[1]) && Number(match[2]) === port);
|
|
118
121
|
}
|
|
119
122
|
|
|
120
|
-
|
|
123
|
+
/**
|
|
124
|
+
* The checks every one of the sidecar's own endpoints makes before answering: a
|
|
125
|
+
* loopback peer, no Origin (a browser's cross-origin request carries one), and a Host
|
|
126
|
+
* naming this loopback listener and port exactly (DNS rebinding). The watch feed and
|
|
127
|
+
* subscription mode's hook endpoint share them.
|
|
128
|
+
*/
|
|
129
|
+
export function isLocalCaller(req, port) {
|
|
130
|
+
const loopbackPeer = LOOPBACK_PEER.test(String(req.socket?.remoteAddress ?? ""));
|
|
131
|
+
return loopbackPeer && req.headers.origin === undefined && hostIsThisListener(req.headers.host, port);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export function answer(res, status, error, message) {
|
|
121
135
|
const body = JSON.stringify({ error, message });
|
|
122
136
|
res.writeHead(status, {
|
|
123
137
|
"content-type": "application/json",
|
|
@@ -136,6 +150,8 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
136
150
|
const ring = [];
|
|
137
151
|
const subscribers = new Set();
|
|
138
152
|
let seq = 0;
|
|
153
|
+
// Subscription mode's usage window (cli/usage-window.mjs): only the latest matters.
|
|
154
|
+
let usageWindow = null;
|
|
139
155
|
|
|
140
156
|
function send(res, line) {
|
|
141
157
|
try {
|
|
@@ -194,6 +210,7 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
194
210
|
status: null,
|
|
195
211
|
ttfb: null,
|
|
196
212
|
ms: null,
|
|
213
|
+
cost: null,
|
|
197
214
|
};
|
|
198
215
|
let announced = false;
|
|
199
216
|
return {
|
|
@@ -223,6 +240,49 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
223
240
|
};
|
|
224
241
|
}
|
|
225
242
|
|
|
243
|
+
/**
|
|
244
|
+
* A call the CLIENT reported (subscription mode: Claude Code's own telemetry,
|
|
245
|
+
* cli/otlp-logs.mjs). It never passed this sidecar, so it is SEEN, not boarded, and
|
|
246
|
+
* its cost is the client's API-equivalent estimate in USD millionths. Never throws.
|
|
247
|
+
*/
|
|
248
|
+
function report({ at = now(), lineage = null, model = null, provider = null, outcome = "seen", status = null, ms = null, cost = null }) {
|
|
249
|
+
try {
|
|
250
|
+
const record = {
|
|
251
|
+
type: "call",
|
|
252
|
+
seq: ++seq,
|
|
253
|
+
at: Number.isFinite(at) ? at : now(),
|
|
254
|
+
ses: held(DECLARED, lineage?.session),
|
|
255
|
+
agent: held(DECLARED, lineage?.agent),
|
|
256
|
+
parent: held(DECLARED, lineage?.parent),
|
|
257
|
+
model: held(MODEL, model),
|
|
258
|
+
provider: held(PROVIDER, provider),
|
|
259
|
+
outcome: outcome === "seen" ? "seen" : "error",
|
|
260
|
+
code: null,
|
|
261
|
+
status: Number.isInteger(status) ? status : null,
|
|
262
|
+
ttfb: null,
|
|
263
|
+
ms: Number.isInteger(ms) && ms >= 0 ? ms : null,
|
|
264
|
+
cost: Number.isInteger(cost) && cost >= 0 ? cost : null,
|
|
265
|
+
};
|
|
266
|
+
remember(record);
|
|
267
|
+
broadcast(record);
|
|
268
|
+
} catch {
|
|
269
|
+
// The feed is never the reason anything fails.
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* The latest usage window, already held to its shape by the caller. Replaces the
|
|
275
|
+
* last one and tells every board. Never throws.
|
|
276
|
+
*/
|
|
277
|
+
function setWindow(window) {
|
|
278
|
+
try {
|
|
279
|
+
usageWindow = { type: "window", fiveHour: window.fiveHour, sevenDay: window.sevenDay, at: now() };
|
|
280
|
+
broadcast(usageWindow);
|
|
281
|
+
} catch {
|
|
282
|
+
// As above.
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
|
|
226
286
|
/** A call whose outcome and end are known at once (refusals, upstream failures). */
|
|
227
287
|
function record({ outcome, code = null, status, lineage = null, model = null, provider = null, startedAt = now() }) {
|
|
228
288
|
const call = begin({ startedAt, lineage, model, provider });
|
|
@@ -234,6 +294,7 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
234
294
|
function attach(res) {
|
|
235
295
|
subscribers.add(res);
|
|
236
296
|
send(res, `${JSON.stringify({ type: "hello", feed: "passcontrol-watch", v: 1, run: runId })}\n`);
|
|
297
|
+
if (usageWindow && subscribers.has(res)) send(res, `${JSON.stringify(usageWindow)}\n`);
|
|
237
298
|
for (const r of ring) if (subscribers.has(res)) send(res, `${JSON.stringify(r)}\n`);
|
|
238
299
|
try {
|
|
239
300
|
res.on("close", () => subscribers.delete(res));
|
|
@@ -251,8 +312,7 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
251
312
|
return answer(res, 404, "watch_off", "This sidecar is bound off loopback, so it serves no watch feed.");
|
|
252
313
|
}
|
|
253
314
|
if (req.method !== "GET") return answer(res, 405, "method_not_allowed", "The watch feed answers GET only.");
|
|
254
|
-
|
|
255
|
-
if (!loopbackPeer || req.headers.origin !== undefined || !hostIsThisListener(req.headers.host, port)) {
|
|
315
|
+
if (!isLocalCaller(req, port)) {
|
|
256
316
|
return answer(res, 403, "watch_refused", "The watch feed is for `passcontrol watch` on this machine only.");
|
|
257
317
|
}
|
|
258
318
|
if (subscribers.size >= maxSubscribers) {
|
|
@@ -271,5 +331,15 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
|
|
|
271
331
|
for (const res of [...subscribers]) drop(res);
|
|
272
332
|
}
|
|
273
333
|
|
|
274
|
-
return {
|
|
334
|
+
return {
|
|
335
|
+
begin,
|
|
336
|
+
record,
|
|
337
|
+
report,
|
|
338
|
+
setWindow,
|
|
339
|
+
window: () => usageWindow,
|
|
340
|
+
serve,
|
|
341
|
+
attach,
|
|
342
|
+
close,
|
|
343
|
+
subscriberCount: () => subscribers.size,
|
|
344
|
+
};
|
|
275
345
|
}
|
package/cli/watch.mjs
CHANGED
|
@@ -18,12 +18,14 @@
|
|
|
18
18
|
import http from "node:http";
|
|
19
19
|
import { formatUsd, limitReached, panelRows } from "./budget-format.mjs";
|
|
20
20
|
import { WATCH_PATH } from "./watch-feed.mjs";
|
|
21
|
+
import { heldUsageWindow, resetTime, usageWindowText } from "./usage-window.mjs";
|
|
21
22
|
|
|
22
23
|
const DECLARED = /^[A-Za-z0-9._:-]{1,128}$/;
|
|
23
24
|
const MODEL = /^[A-Za-z0-9._:/@-]{1,100}$/;
|
|
24
25
|
const CODE = /^[a-z][a-z0-9_]{1,47}$/;
|
|
25
26
|
const PROVIDER = /^[a-z0-9-]{1,32}$/;
|
|
26
|
-
|
|
27
|
+
// "seen" is a call the client reported (subscription mode), not one the sidecar relayed.
|
|
28
|
+
const OUTCOMES = new Set(["boarded", "denied", "error", "seen"]);
|
|
27
29
|
const MAX_ROWS = 500;
|
|
28
30
|
const MAX_LINE = 64 * 1024;
|
|
29
31
|
export const BUDGET_EVERY_MS = 20_000;
|
|
@@ -122,7 +124,7 @@ export function openFeed({ port, host = "127.0.0.1", onEvent, onError = () => {}
|
|
|
122
124
|
// ── State ────────────────────────────────────────────────────────────────────
|
|
123
125
|
|
|
124
126
|
export function createBoardState() {
|
|
125
|
-
return { run: null, rows: [], feed: { state: "connecting" }, budget: null };
|
|
127
|
+
return { run: null, rows: [], feed: { state: "connecting" }, budget: null, window: null };
|
|
126
128
|
}
|
|
127
129
|
|
|
128
130
|
const held = (pattern, value) => (typeof value === "string" && pattern.test(value) ? value : null);
|
|
@@ -154,6 +156,7 @@ export function applyEvent(state, event) {
|
|
|
154
156
|
status: Number.isInteger(event.status) ? event.status : null,
|
|
155
157
|
ttfb: count(event.ttfb),
|
|
156
158
|
ms: count(event.ms),
|
|
159
|
+
cost: count(event.cost),
|
|
157
160
|
};
|
|
158
161
|
const existing = state.rows.findIndex((r) => r.seq === row.seq);
|
|
159
162
|
if (existing === -1) state.rows.push(row);
|
|
@@ -161,6 +164,11 @@ export function applyEvent(state, event) {
|
|
|
161
164
|
if (state.rows.length > MAX_ROWS) state.rows.splice(0, state.rows.length - MAX_ROWS);
|
|
162
165
|
return state;
|
|
163
166
|
}
|
|
167
|
+
if (event.type === "window") {
|
|
168
|
+
const window = heldUsageWindow(event);
|
|
169
|
+
if (window) state.window = window;
|
|
170
|
+
return state;
|
|
171
|
+
}
|
|
164
172
|
if (event.type === "end") {
|
|
165
173
|
const row = state.rows.find((r) => r.seq === event.seq);
|
|
166
174
|
const ms = count(event.ms);
|
|
@@ -217,8 +225,17 @@ export function formatMs(ms) {
|
|
|
217
225
|
|
|
218
226
|
const localTime = (at) => new Date(at).toTimeString().slice(0, 8);
|
|
219
227
|
|
|
228
|
+
/** USD millionths, as one call's cost: four decimals under a dollar. */
|
|
229
|
+
export function formatMicroUsd(micros) {
|
|
230
|
+
if (micros === null || micros === undefined) return "";
|
|
231
|
+
const dollars = micros / 1_000_000;
|
|
232
|
+
return `$${dollars < 1 ? dollars.toFixed(4) : dollars.toFixed(2)}`;
|
|
233
|
+
}
|
|
234
|
+
|
|
220
235
|
function statusText(row) {
|
|
221
236
|
if (row.outcome === "boarded") return "BOARDED";
|
|
237
|
+
// Reported by Claude Code, never relayed: its cost is API-equivalent, not charged.
|
|
238
|
+
if (row.outcome === "seen") return row.cost !== null ? `SEEN ${formatMicroUsd(row.cost)}` : "SEEN";
|
|
222
239
|
if (row.outcome === "denied") return row.code ? `DENIED ${row.code}` : "DENIED";
|
|
223
240
|
return `ERROR ${row.code ?? row.status ?? ""}`.trimEnd();
|
|
224
241
|
}
|
|
@@ -241,8 +258,9 @@ function agentText(row, width) {
|
|
|
241
258
|
|
|
242
259
|
/** Column widths for a terminal `width` wide; the session column goes first when narrow. */
|
|
243
260
|
function columns(width) {
|
|
244
|
-
// Below 80
|
|
245
|
-
|
|
261
|
+
// Below an 80-column window the model and the refusal's reason need the room more.
|
|
262
|
+
// 79, not 80: screenFrame draws one column narrower than the window.
|
|
263
|
+
const withSession = width >= 79;
|
|
246
264
|
const fixed = 8 + (withSession ? 8 : 0) + 12 + 7;
|
|
247
265
|
const gaps = (withSession ? 5 : 4) * 2;
|
|
248
266
|
const rest = Math.max(10, width - fixed - gaps);
|
|
@@ -261,7 +279,8 @@ function rowLine(row, cols, { run, now, formatTime, color }) {
|
|
|
261
279
|
if (cols.withSession) cells.push(fit(sessionText(row, run), cols.session));
|
|
262
280
|
cells.push(agentText(row, cols.agent));
|
|
263
281
|
cells.push(fit(row.model ?? "—", cols.model));
|
|
264
|
-
|
|
282
|
+
const status = fit(statusText(row), cols.status);
|
|
283
|
+
cells.push(BAR_STYLE[row.outcome] ? paint(color, BAR_STYLE[row.outcome], status) : status);
|
|
265
284
|
cells.push(fitRight(latencyText(row, now), cols.latency));
|
|
266
285
|
return cells.join(" ");
|
|
267
286
|
}
|
|
@@ -301,6 +320,13 @@ function budgetLine(budget, width, { color, formatTime }) {
|
|
|
301
320
|
return visibleLength(line + checked) <= width ? line + checked : line;
|
|
302
321
|
}
|
|
303
322
|
|
|
323
|
+
// Subscription mode: how much of Anthropic's 5-hour and 7-day allowance is used, as
|
|
324
|
+
// Claude Code last told the status line (cli/usage-window.mjs). Shown, never enforced.
|
|
325
|
+
function windowLine(window, now) {
|
|
326
|
+
const text = usageWindowText(window, { formatTime: (s) => resetTime(s, now) });
|
|
327
|
+
return text ? `${"Window".padEnd(9)} ${text}` : "";
|
|
328
|
+
}
|
|
329
|
+
|
|
304
330
|
function feedText(feed, port) {
|
|
305
331
|
switch (feed?.state) {
|
|
306
332
|
case "live":
|
|
@@ -342,6 +368,18 @@ function clip(line, width) {
|
|
|
342
368
|
* The whole board as `height` lines, none wider than `width`. Pure: the same state,
|
|
343
369
|
* size and clock give the same lines.
|
|
344
370
|
*/
|
|
371
|
+
/**
|
|
372
|
+
* The full-screen frame draw() writes: home, each board line, clear the rest.
|
|
373
|
+
*
|
|
374
|
+
* One column narrower than the window. A line that fills the last column leaves the
|
|
375
|
+
* cursor ON that column (the terminal's pending-wrap state), and the ESC[K after it
|
|
376
|
+
* erases from the cursor, so the line's last character vanished ("LATENC").
|
|
377
|
+
*/
|
|
378
|
+
export function screenFrame(state, { columns, rows, port, color = false, now, formatTime }) {
|
|
379
|
+
const lines = renderBoard(state, { width: Math.max(1, columns - 1), height: rows, port, color, now, formatTime });
|
|
380
|
+
return `\x1b[H${lines.map((l) => `${l}\x1b[K`).join("\r\n")}\x1b[J`;
|
|
381
|
+
}
|
|
382
|
+
|
|
345
383
|
export function renderBoard(state, { width, height, port, now = Date.now(), formatTime = localTime, color = false }) {
|
|
346
384
|
const w = Math.max(1, Math.floor(width));
|
|
347
385
|
const h = Math.max(1, Math.floor(height));
|
|
@@ -352,17 +390,19 @@ export function renderBoard(state, { width, height, port, now = Date.now(), form
|
|
|
352
390
|
}
|
|
353
391
|
const cols = columns(w);
|
|
354
392
|
const rows = state.rows;
|
|
355
|
-
const tally = { boarded: 0, denied: 0, error: 0 };
|
|
393
|
+
const tally = { boarded: 0, denied: 0, error: 0, seen: 0 };
|
|
356
394
|
for (const r of rows) tally[r.outcome] += 1;
|
|
357
395
|
const counts = rows.length
|
|
358
|
-
? `${rows.length} call${rows.length === 1 ? "" : "s"}: ${tally.boarded} boarded, ${tally.denied} denied${tally.error ? `, ${tally.error} error` : ""}`
|
|
396
|
+
? `${rows.length} call${rows.length === 1 ? "" : "s"}: ${tally.seen ? `${tally.seen} seen, ` : ""}${tally.boarded} boarded, ${tally.denied} denied${tally.error ? `, ${tally.error} error` : ""}`
|
|
359
397
|
: "no calls yet";
|
|
360
398
|
const lines = [
|
|
361
399
|
`${paint(color, "bold", "PassControl watch")} · sidecar :${port} · ${feedText(state.feed, port)} · ${counts}`,
|
|
362
400
|
budgetLine(state.budget, w, { color, formatTime }),
|
|
363
401
|
// Why the board is not live, on a line of its own so it is never cut off the end
|
|
364
402
|
// of the header. Older rows stay below it: they happened.
|
|
365
|
-
state.feed?.state === "down"
|
|
403
|
+
state.feed?.state === "down"
|
|
404
|
+
? paint(color, "yellow", clean(state.feed.message ?? `waiting for the sidecar on :${port}`))
|
|
405
|
+
: windowLine(state.window, now),
|
|
366
406
|
];
|
|
367
407
|
const header = ["TIME".padEnd(cols.time)];
|
|
368
408
|
if (cols.withSession) header.push("SESSION".padEnd(cols.session));
|
|
@@ -478,8 +518,7 @@ export function runWatch({
|
|
|
478
518
|
drawTimer = null;
|
|
479
519
|
if (finished) return;
|
|
480
520
|
if (tty) {
|
|
481
|
-
|
|
482
|
-
out.write(`\x1b[H${lines.map((l) => `${l}\x1b[K`).join("\r\n")}\x1b[J`);
|
|
521
|
+
out.write(screenFrame(state, { columns: out.columns || 80, rows: out.rows || 24, port, color }));
|
|
483
522
|
return;
|
|
484
523
|
}
|
|
485
524
|
const feedLine = state.feed?.state === "down" ? clean(state.feed.message ?? "") : state.feed?.state === "live" ? "connected" : null;
|
package/package.json
CHANGED