passcontrol 0.9.4 → 1.0.0
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 +242 -135
- package/bin/passcontrol.mjs +348 -35
- package/cli/config.mjs +129 -4
- package/cli/integration-defaults.mjs +5 -5
- package/cli/mcp/README.md +2 -0
- package/cli/menu.mjs +1 -0
- package/cli/update-check.mjs +7 -3
- package/cli/update.mjs +214 -0
- package/package.json +1 -1
- package/sdk/README.md +8 -6
- package/sdk/control.d.ts +3 -0
package/cli/config.mjs
CHANGED
|
@@ -205,7 +205,46 @@ export function assertConfigLoaded() {
|
|
|
205
205
|
}
|
|
206
206
|
|
|
207
207
|
export function resolveModel(provider) {
|
|
208
|
-
|
|
208
|
+
// `||`, not `??`: the config writer emits every key, so a fresh login left
|
|
209
|
+
// `MODEL=` in the file, and an empty string is not a model.
|
|
210
|
+
return process.env.MODEL || defaultModelForProvider(provider);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Provider and gateway, with an EMPTY value treated as unset. The config writer
|
|
215
|
+
* emits every key, so a fresh `login` wrote `PROVIDER=` — and `??` kept the empty
|
|
216
|
+
* string, so bare `call` and `agent create` failed with `Unknown provider ""`
|
|
217
|
+
* (1.0.0 self-host E2E). Reading empty as unset also repairs the configs 0.9.x
|
|
218
|
+
* logins already wrote.
|
|
219
|
+
*/
|
|
220
|
+
export function resolveConfigDefaults(env = process.env) {
|
|
221
|
+
return {
|
|
222
|
+
provider: env.PROVIDER || DEFAULT_PROVIDER,
|
|
223
|
+
gateway: trimSlash(env.PASSCONTROL_GATEWAY || DEFAULT_GATEWAY),
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* What `setup` writes to the global config when it activates a local stack.
|
|
229
|
+
*
|
|
230
|
+
* Switching away from another gateway also forgets that gateway's credentials.
|
|
231
|
+
* Otherwise it still RECORDS the local gateway when the file names none: with no
|
|
232
|
+
* config the CLI's built-in default is already localhost, so setup used to think
|
|
233
|
+
* nothing needed writing — while `login`, which deliberately ignores that
|
|
234
|
+
* default, then went to Cloud. Null when the file already names a gateway.
|
|
235
|
+
*/
|
|
236
|
+
export function localActivationPatch({ switching, globalValues = {}, targetUrl }) {
|
|
237
|
+
if (switching) {
|
|
238
|
+
return {
|
|
239
|
+
PASSCONTROL_GATEWAY: targetUrl,
|
|
240
|
+
PASSPORT_ID: "",
|
|
241
|
+
PASSPORT_SECRET: "",
|
|
242
|
+
PASSPORT_KEY_STORAGE: "",
|
|
243
|
+
PASSCONTROL_API_KEY: "",
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
if (!String(globalValues.PASSCONTROL_GATEWAY ?? "").trim()) return { PASSCONTROL_GATEWAY: targetUrl };
|
|
247
|
+
return null;
|
|
209
248
|
}
|
|
210
249
|
|
|
211
250
|
export function resolvedConfig() {
|
|
@@ -214,7 +253,7 @@ export function resolvedConfig() {
|
|
|
214
253
|
}
|
|
215
254
|
|
|
216
255
|
function currentConfig() {
|
|
217
|
-
const provider = process.env
|
|
256
|
+
const { provider, gateway } = resolveConfigDefaults(process.env);
|
|
218
257
|
const passportId = process.env.PASSPORT_ID ?? "";
|
|
219
258
|
const fileSecret = process.env.PASSPORT_SECRET ?? "";
|
|
220
259
|
const passportStorageMarker = process.env.PASSPORT_KEY_STORAGE ?? "";
|
|
@@ -234,7 +273,7 @@ function currentConfig() {
|
|
|
234
273
|
return passport;
|
|
235
274
|
};
|
|
236
275
|
return {
|
|
237
|
-
gateway
|
|
276
|
+
gateway,
|
|
238
277
|
passportId,
|
|
239
278
|
get passportSecret() {
|
|
240
279
|
return resolvedPassport().secret;
|
|
@@ -431,6 +470,42 @@ export function requireControlApiKey(current = config) {
|
|
|
431
470
|
*/
|
|
432
471
|
const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
|
|
433
472
|
|
|
473
|
+
/**
|
|
474
|
+
* A value that still carries its own quote characters, explained.
|
|
475
|
+
*
|
|
476
|
+
* `cmd.exe` does not treat `'` as quoting. A Windows operator copying a POSIX
|
|
477
|
+
* invocation out of a README types `--gateway 'http://localhost:3000'` and the
|
|
478
|
+
* CLI receives those quotes as part of the argument — so a value that is right
|
|
479
|
+
* on the line they typed is refused by a message about the string that arrived.
|
|
480
|
+
* The same trap already broke `npm run dev:docker`, which was a bash one-liner
|
|
481
|
+
* in single quotes until cmd handed bash `'set` as its whole command; see the
|
|
482
|
+
* header of `scripts/dev-docker.mjs`.
|
|
483
|
+
*
|
|
484
|
+
* Deliberately a hint and not a repair. The callers below validate values that
|
|
485
|
+
* decide where a credential is sent, and quietly normalizing an argument before
|
|
486
|
+
* a strict rule sees it is how strict rules stop being strict. This only
|
|
487
|
+
* explains the refusal.
|
|
488
|
+
*
|
|
489
|
+
* Returns a sentence to append, or "". It describes the shape and never the
|
|
490
|
+
* value: a gateway URL or a passport id can itself be a credential.
|
|
491
|
+
*
|
|
492
|
+
* @param {unknown} value
|
|
493
|
+
* @returns {string}
|
|
494
|
+
*/
|
|
495
|
+
export function shellQuotingHint(value) {
|
|
496
|
+
const text = String(value ?? "");
|
|
497
|
+
if (text.length < 2) return "";
|
|
498
|
+
const quote = text[0];
|
|
499
|
+
if ((quote !== "'" && quote !== '"') || text[text.length - 1] !== quote) return "";
|
|
500
|
+
// Only single quotes get the cmd.exe sentence: cmd *does* strip double
|
|
501
|
+
// quotes, so a value that arrives wrapped in them came from a config file or
|
|
502
|
+
// another shell, and naming cmd would send the reader somewhere wrong.
|
|
503
|
+
const cause =
|
|
504
|
+
quote === "'" ? " Windows cmd.exe does not treat ' as quoting and passes it through literally." : "";
|
|
505
|
+
const name = quote === "'" ? "a single quote" : "a double quote";
|
|
506
|
+
return ` The value starts and ends with ${name}, so the quote characters are part of it.${cause} Retype it with no quotes around it.`;
|
|
507
|
+
}
|
|
508
|
+
|
|
434
509
|
/**
|
|
435
510
|
* Validate a gateway value and return the origin to build URLs from.
|
|
436
511
|
*
|
|
@@ -452,6 +527,11 @@ const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
|
|
|
452
527
|
* prints the message and exits 1, and `doctor` catches it to report a failed
|
|
453
528
|
* check instead of vanishing mid-diagnosis. The message never quotes the value,
|
|
454
529
|
* because a rejected gateway can itself carry credentials.
|
|
530
|
+
*
|
|
531
|
+
* The unparseable branch appends `shellQuotingHint`, which the SDK has no reason
|
|
532
|
+
* to carry — it is never handed a cmd.exe argv. That is a message, not a rule:
|
|
533
|
+
* what this accepts and refuses is still identical to the SDK's, which is all
|
|
534
|
+
* the parity test asserts.
|
|
455
535
|
*/
|
|
456
536
|
export function bareGatewayOrigin(gateway, label = "PASSCONTROL_GATEWAY") {
|
|
457
537
|
let url;
|
|
@@ -459,7 +539,8 @@ export function bareGatewayOrigin(gateway, label = "PASSCONTROL_GATEWAY") {
|
|
|
459
539
|
url = new URL(String(gateway ?? ""));
|
|
460
540
|
} catch {
|
|
461
541
|
throw new Error(
|
|
462
|
-
`${label} must be an absolute URL (for example https://passcontrol.example.com).`
|
|
542
|
+
`${label} must be an absolute URL (for example https://passcontrol.example.com).` +
|
|
543
|
+
shellQuotingHint(gateway)
|
|
463
544
|
);
|
|
464
545
|
}
|
|
465
546
|
const loopback = LOOPBACK_HOSTNAMES.has(url.hostname);
|
|
@@ -556,8 +637,52 @@ export function formatChallengeError(status, body) {
|
|
|
556
637
|
return `Challenge failed: ${status} ${detail}`;
|
|
557
638
|
}
|
|
558
639
|
|
|
640
|
+
/** The gateway's JSON error body, or {} when it is not one. */
|
|
641
|
+
function errorBody(detail) {
|
|
642
|
+
try {
|
|
643
|
+
const parsed = JSON.parse(detail);
|
|
644
|
+
return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
|
|
645
|
+
} catch {
|
|
646
|
+
return {};
|
|
647
|
+
}
|
|
648
|
+
}
|
|
649
|
+
|
|
559
650
|
export function formatProxyError(status, body) {
|
|
560
651
|
const detail = String(body ?? "").trim();
|
|
652
|
+
const { error, rule, reason, limit } = errorBody(detail);
|
|
653
|
+
const blocked = `Proxy blocked the call with ${status}: ${detail}`;
|
|
654
|
+
if (status === 402 && error === "blocked_budget_period") {
|
|
655
|
+
return `${blocked}\n→ The agent's daily or monthly limit is spent; it resets at the next UTC day or month (see the retry-after header).\n→ Fix: wait for the reset, or raise the limit in the dashboard.`;
|
|
656
|
+
}
|
|
657
|
+
if (status === 403 && error === "blocked_policy" && rule === "max_output_tokens") {
|
|
658
|
+
const ceiling = Number.isSafeInteger(limit) ? ` (${limit})` : "";
|
|
659
|
+
return reason === "missing"
|
|
660
|
+
? `${blocked}\n→ The agent's policy has an output ceiling${ceiling}, and this request did not state an output limit.\n→ Fix: state an output limit — max_tokens (or max_completion_tokens / max_output_tokens) no higher than the ceiling.`
|
|
661
|
+
: `${blocked}\n→ The request asked for more output than the agent's output ceiling${ceiling}.\n→ Fix: send a smaller max_tokens, or raise the ceiling in the agent's policy.`;
|
|
662
|
+
}
|
|
663
|
+
if (status === 403 && error === "blocked_policy") {
|
|
664
|
+
return `${blocked}\n→ A rule in the agent's live policy refused this call (a deny rule, time window or hourly cap).\n→ Fix: review the policy on the agent's page, or use its decision trace to see which rule.`;
|
|
665
|
+
}
|
|
666
|
+
if (status === 403 && error === "blocked_scope") {
|
|
667
|
+
return `${blocked}\n→ This provider and model are outside the agent's allowed models.\n→ Fix: call an allowed model, or widen the agent's scope in the dashboard.`;
|
|
668
|
+
}
|
|
669
|
+
if (status === 409 && error === "no_provider_key") {
|
|
670
|
+
return `${blocked}\n→ The workspace has no provider key stored for this provider.\n→ Fix: add one under Settings → Provider credentials in the dashboard.`;
|
|
671
|
+
}
|
|
672
|
+
if (status === 400 && error === "server_side_tools_unsupported") {
|
|
673
|
+
return `${blocked}\n→ The request uses a hosted tool (such as web search) that the provider bills outside tokens, which no budget here can hold.\n→ Fix: remove the hosted tool, or call that feature outside PassControl.`;
|
|
674
|
+
}
|
|
675
|
+
// 402 is also how the gateway refuses a call it cannot price under a dollar
|
|
676
|
+
// limit; a bigger budget fixes none of those, so each gets its own advice.
|
|
677
|
+
if (status === 402 && error === "unpriced_model") {
|
|
678
|
+
return `${blocked}\n→ PassControl has no price for this model, so the agent's dollar limit cannot be enforced against it.\n→ Fix: use a model PassControl prices, or remove the dollar limit (a token cap still works).`;
|
|
679
|
+
}
|
|
680
|
+
if (status === 402 && error === "unpriced_option") {
|
|
681
|
+
return `${blocked}\n→ The named request field bills above the model's listed price, so the agent's dollar limit cannot hold it.\n→ Fix: drop that field (e.g. service_tier), or remove the dollar limit.`;
|
|
682
|
+
}
|
|
683
|
+
if (status === 402 && error === "unpriced_endpoint") {
|
|
684
|
+
return `${blocked}\n→ This agent's provider goes through a custom endpoint PassControl cannot price, so its dollar limit cannot be enforced.\n→ Fix: remove the dollar limit (a token cap still works), or use the provider's own endpoint.`;
|
|
685
|
+
}
|
|
561
686
|
if (status === 402) {
|
|
562
687
|
return `Proxy blocked the call with 402: ${detail}\n→ Fix: raise or clear the agent budget in the dashboard, then retry.`;
|
|
563
688
|
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
8
8
|
anthropic: "claude-*",
|
|
9
9
|
openai: "gpt-*",
|
|
10
|
-
groq: "
|
|
10
|
+
groq: "openai/gpt-oss-*",
|
|
11
11
|
mistral: "mistral-*",
|
|
12
12
|
together: "openai/gpt-oss-*",
|
|
13
13
|
deepseek: "deepseek-*",
|
|
@@ -17,11 +17,11 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
|
17
17
|
export const DEFAULT_CLIENT_MODELS = Object.freeze({
|
|
18
18
|
anthropic: "claude-haiku-4-5",
|
|
19
19
|
openai: "gpt-5-mini",
|
|
20
|
-
groq: "
|
|
20
|
+
groq: "openai/gpt-oss-20b",
|
|
21
21
|
mistral: "mistral-small-latest",
|
|
22
|
-
together: "openai/gpt-oss-
|
|
23
|
-
deepseek: "deepseek-
|
|
24
|
-
gemini: "gemini-
|
|
22
|
+
together: "openai/gpt-oss-120b",
|
|
23
|
+
deepseek: "deepseek-flash",
|
|
24
|
+
gemini: "gemini-3.8-flash",
|
|
25
25
|
});
|
|
26
26
|
|
|
27
27
|
export function defaultAllowedModelForProvider(provider) {
|
package/cli/mcp/README.md
CHANGED
|
@@ -6,6 +6,8 @@ It reads the same environment, nearest `.passcontrol`, and global
|
|
|
6
6
|
passport in the global profile so clients can launch from any working directory without
|
|
7
7
|
embedding a secret:
|
|
8
8
|
|
|
9
|
+
On Windows, run these shell commands in PowerShell. Replace placeholders before running.
|
|
10
|
+
|
|
9
11
|
```sh
|
|
10
12
|
passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST --id PUBLIC_PASSPORT_ID
|
|
11
13
|
# paste the one-time secret at the hidden prompt
|
package/cli/menu.mjs
CHANGED
|
@@ -226,6 +226,7 @@ export const GROUPS = [
|
|
|
226
226
|
command({ id: "doctor", label: "Diagnose setup", run: ["doctor"], detail: "doctor", description: "Inspect the local stack, gateway, credentials, and protocol compatibility.", network: "gateway", current: currentFrom("gateway") }),
|
|
227
227
|
command({ id: "status", label: "Show cockpit status", run: ["status"], detail: "status", description: "Show local configuration, gateway health, and the next useful action.", network: "gateway", current: currentFrom("gateway") }),
|
|
228
228
|
command({ id: "version", label: "CLI, gateway and schema versions", run: ["version"], detail: "version", description: "Compare CLI, gateway build, schema, and protocol versions.", network: "gateway" }),
|
|
229
|
+
command({ id: "update", label: "Update PassControl", run: ["update"], detail: "update [--check]", description: "Update the CLI and the local app: code, dependencies, migrations.", effect: "irreversible", network: "provider", keywords: ["upgrade", "new version", "migrate"] }),
|
|
229
230
|
command({ id: "open", label: "Open the Control Tower", run: ["open"], detail: "open", description: "Open the configured dashboard in the system browser.", effect: "launch", network: "browser" }),
|
|
230
231
|
command({ id: "call", label: "Make a governed model call", run: ["call"], detail: "call \"<prompt>\"", description: "Mint a visa and make a billable governed provider call.", effect: "tenant_write", network: "provider", needsArgs: true, current: currentFrom("provider") }),
|
|
231
232
|
],
|
package/cli/update-check.mjs
CHANGED
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
// wall-clock time rather than by how often the CLI is run.
|
|
17
17
|
//
|
|
18
18
|
// It reports only that a newer version exists. It never downloads, installs or
|
|
19
|
-
// runs anything — upgrading stays a thing the operator types
|
|
19
|
+
// runs anything — upgrading stays a thing the operator types (`passcontrol update`,
|
|
20
|
+
// cli/update.mjs, which asks before it changes anything).
|
|
20
21
|
import fs from "node:fs";
|
|
21
22
|
import os from "node:os";
|
|
22
23
|
import path from "node:path";
|
|
@@ -110,7 +111,7 @@ export function writeCache(file, data) {
|
|
|
110
111
|
/** The notice itself, or null when there is nothing worth saying. */
|
|
111
112
|
export function updateNotice(current, latest) {
|
|
112
113
|
if (!isNewer(latest, current)) return null;
|
|
113
|
-
return `Update available ${current} → ${latest}
|
|
114
|
+
return `Update available ${current} → ${latest} passcontrol update`;
|
|
114
115
|
}
|
|
115
116
|
|
|
116
117
|
/**
|
|
@@ -124,7 +125,10 @@ export async function fetchLatest(url = REGISTRY_URL, timeoutMs = 1500, fetchImp
|
|
|
124
125
|
try {
|
|
125
126
|
const res = await fetchImpl(url, {
|
|
126
127
|
signal: controller.signal,
|
|
127
|
-
|
|
128
|
+
// Plain JSON. The abbreviated-metadata type is for the full packument; on
|
|
129
|
+
// /latest the registry answers 406 to it, which made every check return
|
|
130
|
+
// null and no notice was ever shown (found 2026-09-27).
|
|
131
|
+
headers: { accept: "application/json" },
|
|
128
132
|
});
|
|
129
133
|
if (!res.ok) return null;
|
|
130
134
|
const body = await res.json();
|
package/cli/update.mjs
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
// `passcontrol update` — the decisions, kept pure so every one of them is tested
|
|
2
|
+
// before it touches someone's install. bin/passcontrol.mjs does the mutating
|
|
3
|
+
// half (npm, git, the local stack) and asks this module what to do.
|
|
4
|
+
//
|
|
5
|
+
// Two things get updated, and they fail differently:
|
|
6
|
+
//
|
|
7
|
+
// * The CLI. Only an npm global install is updated in place, pinned to the
|
|
8
|
+
// exact version just read from the registry (not `@latest`, so a release
|
|
9
|
+
// published mid-update cannot slip in). npx, pnpm, yarn, bun, volta and a
|
|
10
|
+
// source checkout each get the right command PRINTED: guessing another
|
|
11
|
+
// package manager's layout is how a tool ends up installed twice.
|
|
12
|
+
// * The self-host app checkout `setup` made — a clone of the PUBLIC repo only.
|
|
13
|
+
// Fast-forward, never merge; refuse on local edits, a diverged branch, or a
|
|
14
|
+
// checkout that is not the public repo (a private or forked checkout is its
|
|
15
|
+
// owner's to update). Migrations only go forward, so the plan names them.
|
|
16
|
+
import fs from "node:fs";
|
|
17
|
+
import os from "node:os";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
|
|
20
|
+
import { isNewer } from "./update-check.mjs";
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* How this CLI was installed, and how to update it.
|
|
24
|
+
*
|
|
25
|
+
* `command` is non-null only when running it is safe: an npm global install
|
|
26
|
+
* whose prefix can be read off the script's own path. Everything else gets a
|
|
27
|
+
* `manual` line to print.
|
|
28
|
+
*/
|
|
29
|
+
export function detectInstall({ scriptPath, platform = process.platform, isSourceCheckout = false, version }) {
|
|
30
|
+
const spec = `passcontrol@${version}`;
|
|
31
|
+
const p = String(scriptPath ?? "");
|
|
32
|
+
const has = (fragment) => p.replace(/\\/gu, "/").includes(fragment);
|
|
33
|
+
if (isSourceCheckout) {
|
|
34
|
+
return { method: "source", command: null, manual: "This CLI runs from a source checkout: update it with `git pull` there." };
|
|
35
|
+
}
|
|
36
|
+
if (has("/_npx/")) return { method: "npx", command: null, manual: `npx passcontrol@${version} (npx runs a fresh copy; nothing to install)` };
|
|
37
|
+
if (has("/pnpm/") || has("/.pnpm/")) return { method: "pnpm", command: null, manual: `pnpm add -g ${spec}` };
|
|
38
|
+
if (has("/yarn/global/") || has("/.yarn/")) return { method: "yarn", command: null, manual: `yarn global add ${spec}` };
|
|
39
|
+
if (has("/.bun/")) return { method: "bun", command: null, manual: `bun add -g ${spec}` };
|
|
40
|
+
if (has("/.volta/")) return { method: "volta", command: null, manual: `volta install ${spec}` };
|
|
41
|
+
|
|
42
|
+
const windows = platform === "win32";
|
|
43
|
+
const match = windows
|
|
44
|
+
? /^(.*)\\node_modules\\passcontrol\\bin\\passcontrol\.mjs$/iu.exec(p)
|
|
45
|
+
: /^(.*)\/lib\/node_modules\/passcontrol\/bin\/passcontrol\.mjs$/u.exec(p);
|
|
46
|
+
if (match && match[1]) {
|
|
47
|
+
const prefix = match[1];
|
|
48
|
+
return {
|
|
49
|
+
method: "npm-global",
|
|
50
|
+
prefix,
|
|
51
|
+
command: [windows ? "npm.cmd" : "npm", "install", "-g", "--prefix", prefix, spec],
|
|
52
|
+
manual: `npm install -g --prefix ${prefix} ${spec}`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
return { method: "unknown", command: null, manual: `npm install -g ${spec}` };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** `github.com/owner/repo`, lowercased, from any of the forms git accepts. */
|
|
59
|
+
function normalizeRepoUrl(url) {
|
|
60
|
+
let s = String(url ?? "").trim().toLowerCase();
|
|
61
|
+
s = s.replace(/^git@([^:]+):/u, "$1/");
|
|
62
|
+
s = s.replace(/^[a-z+]+:\/\//u, "");
|
|
63
|
+
s = s.replace(/^[^@/]+@/u, "");
|
|
64
|
+
s = s.replace(/\/+$/u, "").replace(/\.git$/u, "");
|
|
65
|
+
return s;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Exact host, owner and repo — never a prefix or substring match. */
|
|
69
|
+
export function isPublicRepoUrl(url, publicUrl) {
|
|
70
|
+
const a = normalizeRepoUrl(url);
|
|
71
|
+
return a !== "" && a === normalizeRepoUrl(publicUrl);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Tracked files with local changes that must stop an update.
|
|
76
|
+
*
|
|
77
|
+
* `package-lock.json` is tolerated: `npm install` rewrites it (the 0.9.5 mirror
|
|
78
|
+
* shipped a stale root version, so every setup checkout shows it modified), it
|
|
79
|
+
* is npm's output rather than anyone's work, and the update restores it and
|
|
80
|
+
* then runs `npm ci`. Untracked files are left to the fast-forward, which names
|
|
81
|
+
* any real collision itself.
|
|
82
|
+
*/
|
|
83
|
+
export function dirtyBlockers(porcelain) {
|
|
84
|
+
const files = [];
|
|
85
|
+
for (const raw of String(porcelain ?? "").split("\n")) {
|
|
86
|
+
const line = raw.replace(/\r$/u, "");
|
|
87
|
+
if (!line.trim()) continue;
|
|
88
|
+
// Two status columns, a space, the path. A caller that trimmed git's output
|
|
89
|
+
// leaves the FIRST line with one column (" M x" → "M x"), so accept that
|
|
90
|
+
// too rather than reading columns by position (which once saw "ackage-lock.json").
|
|
91
|
+
const match = /^([ MADRCUT?!]{2}) (.+)$/u.exec(line) ?? /^([MADRCUT?!]) (.+)$/u.exec(line);
|
|
92
|
+
if (!match) continue;
|
|
93
|
+
const status = match[1].trim();
|
|
94
|
+
if (status === "??" || status === "!!") continue;
|
|
95
|
+
if (match[2] !== "package-lock.json") files.push(match[2]);
|
|
96
|
+
}
|
|
97
|
+
return files;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The project id and port offset `setup` baked into supabase/config.toml, or
|
|
102
|
+
* null. Read back rather than re-derived, because re-running the stack with a
|
|
103
|
+
* different offset or id brings up a FRESH, EMPTY Supabase project — which
|
|
104
|
+
* looks exactly like data loss.
|
|
105
|
+
*/
|
|
106
|
+
export function stackFromConfig(configText) {
|
|
107
|
+
const text = String(configText ?? "");
|
|
108
|
+
const projectId = /^project_id\s*=\s*"([^"]+)"\s*$/mu.exec(text)?.[1];
|
|
109
|
+
const api = /^\[api\]\s*\n(?:[^[]*?\n)?port\s*=\s*(\d+)/mu.exec(text)?.[1];
|
|
110
|
+
if (!projectId || !api) return null;
|
|
111
|
+
const offset = Number(api) - 54321;
|
|
112
|
+
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) return null;
|
|
113
|
+
return { projectId, offset };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** The id scripts/dev-stack.sh will compute for this directory and offset. */
|
|
117
|
+
export function expectedProjectId(dirName, offset) {
|
|
118
|
+
return offset === 0 ? dirName : `${dirName}-${offset}`;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* What an update would do. `app.status` is one of:
|
|
123
|
+
* none — no self-host checkout on this machine (a Cloud user)
|
|
124
|
+
* current — at the public repo's tip
|
|
125
|
+
* behind — fast-forwardable; `behind`, `from`, `to`, `migrations`
|
|
126
|
+
* refuse — `reason` says why this checkout is left alone
|
|
127
|
+
* `app.resume` is set when an earlier update stopped part way.
|
|
128
|
+
*/
|
|
129
|
+
export function planUpdate({ current, latest, install, app }) {
|
|
130
|
+
const cli = {
|
|
131
|
+
reachable: typeof latest === "string",
|
|
132
|
+
needed: typeof latest === "string" && isNewer(latest, current),
|
|
133
|
+
from: current,
|
|
134
|
+
to: latest ?? null,
|
|
135
|
+
command: install?.command ?? null,
|
|
136
|
+
manual: install?.manual ?? "",
|
|
137
|
+
method: install?.method ?? "unknown",
|
|
138
|
+
};
|
|
139
|
+
const appWork = app?.status === "behind" || Boolean(app?.resume);
|
|
140
|
+
return { cli, app: app ?? { status: "none" }, nothingToDo: !cli.needed && !appWork };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The plan as lines for a terminal. */
|
|
144
|
+
export function formatPlan(plan) {
|
|
145
|
+
const lines = [];
|
|
146
|
+
const { cli, app } = plan;
|
|
147
|
+
if (!cli.reachable) {
|
|
148
|
+
lines.push("CLI: could not reach the npm registry, so it is not known whether a newer version exists.");
|
|
149
|
+
} else if (cli.needed) {
|
|
150
|
+
lines.push(`CLI: ${cli.from} → ${cli.to}`);
|
|
151
|
+
lines.push(cli.command ? ` runs: ${cli.command.join(" ")}` : ` run it yourself: ${cli.manual}`);
|
|
152
|
+
} else {
|
|
153
|
+
lines.push(`CLI: ${cli.from}, nothing newer on npm (latest published: ${cli.to}).`);
|
|
154
|
+
}
|
|
155
|
+
switch (app.status) {
|
|
156
|
+
case "none":
|
|
157
|
+
lines.push("App: no self-host checkout on this machine.");
|
|
158
|
+
break;
|
|
159
|
+
case "refuse":
|
|
160
|
+
lines.push(`App: left alone — ${app.reason}`);
|
|
161
|
+
break;
|
|
162
|
+
case "current":
|
|
163
|
+
lines.push(app.resume ? "App: at the latest commit, but an earlier update was interrupted; it will finish install, migrations and restart." : "App: up to date.");
|
|
164
|
+
break;
|
|
165
|
+
case "behind": {
|
|
166
|
+
lines.push(`App: ${app.behind} new commit(s), ${app.from} → ${app.to}`);
|
|
167
|
+
const migrations = app.migrations ?? [];
|
|
168
|
+
lines.push(
|
|
169
|
+
migrations.length
|
|
170
|
+
? ` new database migrations (they only go forward): ${migrations.map((m) => path.basename(m)).join(", ")}`
|
|
171
|
+
: " no new database migrations"
|
|
172
|
+
);
|
|
173
|
+
lines.push(" steps: stop the dashboard, fast-forward, npm ci, apply migrations, start the dashboard again if it was running");
|
|
174
|
+
break;
|
|
175
|
+
}
|
|
176
|
+
default:
|
|
177
|
+
break;
|
|
178
|
+
}
|
|
179
|
+
return lines;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// ── Resume marker ─────────────────────────────────────────────────────────────
|
|
183
|
+
//
|
|
184
|
+
// Written before the first change to the checkout and cleared on success. After
|
|
185
|
+
// a fast-forward HEAD already equals the target, so without it a failed
|
|
186
|
+
// `npm ci` or migration would read as "up to date" on the next run.
|
|
187
|
+
|
|
188
|
+
export function markerPath(env = process.env) {
|
|
189
|
+
const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
190
|
+
return path.join(base, "passcontrol", "update-in-progress.json");
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export function readMarker(env = process.env) {
|
|
194
|
+
try {
|
|
195
|
+
const value = JSON.parse(fs.readFileSync(markerPath(env), "utf8"));
|
|
196
|
+
return value && typeof value.appRoot === "string" ? value : null;
|
|
197
|
+
} catch {
|
|
198
|
+
return null;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export function writeMarker(marker, env = process.env) {
|
|
203
|
+
const file = markerPath(env);
|
|
204
|
+
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
205
|
+
fs.writeFileSync(file, `${JSON.stringify(marker)}\n`, { mode: 0o600 });
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
export function clearMarker(env = process.env) {
|
|
209
|
+
try {
|
|
210
|
+
fs.rmSync(markerPath(env), { force: true });
|
|
211
|
+
} catch {
|
|
212
|
+
// Nothing to clear.
|
|
213
|
+
}
|
|
214
|
+
}
|
package/package.json
CHANGED
package/sdk/README.md
CHANGED
|
@@ -7,12 +7,14 @@ your existing OpenAI/Anthropic SDK, **not rewriting the agent**.
|
|
|
7
7
|
|
|
8
8
|
Install it beside the provider SDK used by your agent:
|
|
9
9
|
|
|
10
|
+
On Windows, run these shell commands in PowerShell. Replace placeholders before running.
|
|
11
|
+
|
|
10
12
|
```bash
|
|
11
|
-
npm install passcontrol
|
|
12
|
-
# or: npm install passcontrol
|
|
13
|
+
npm install passcontrol openai
|
|
14
|
+
# or: npm install passcontrol @anthropic-ai/sdk
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
Dependencies:
|
|
17
|
+
Dependencies: [`@noble/curves`](https://github.com/paulmillr/noble-curves), `@noble/hashes`, and the
|
|
16
18
|
platform `fetch`/`crypto`. Runs on Node 18+ and edge/server runtimes.
|
|
17
19
|
|
|
18
20
|
> Keep `passportSecret` in the trusted agent runtime and out of source control, logs,
|
|
@@ -105,7 +107,7 @@ const res = await pc.fetch(`${gateway}/api/v1/anthropic/v1/messages`, {
|
|
|
105
107
|
## Control-plane SDK (manage your fleet)
|
|
106
108
|
|
|
107
109
|
Separate from the data-plane client above: `ControlClient` (in `./control`) is a typed
|
|
108
|
-
wrapper over the
|
|
110
|
+
wrapper over the workspace control API (`/api/control/v1`), authenticated with a `pc_` API key.
|
|
109
111
|
It mirrors the REST resources, unwraps the `{ data }` envelope, and throws
|
|
110
112
|
`ControlApiError` (with `status`, `code`, `requestId`) on failure.
|
|
111
113
|
|
|
@@ -153,14 +155,14 @@ The full reference lives in [the public OpenAPI document](https://github.com/Ver
|
|
|
153
155
|
the gateway only ever sees the public key and the signature.
|
|
154
156
|
|
|
155
157
|
|
|
156
|
-
##
|
|
158
|
+
## Compatibility and assurance
|
|
157
159
|
|
|
158
160
|
`clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
|
|
159
161
|
and `gemini`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
|
|
160
162
|
Chat Completions. Gemini uses Google's OpenAI-compatible endpoint; native
|
|
161
163
|
`generateContent` is not supported. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
|
|
162
164
|
|
|
163
|
-
The TypeScript SDK **does not attach sender proofs
|
|
165
|
+
The TypeScript SDK **does not attach sender proofs**. Its provider requests use
|
|
164
166
|
bearer visas: they work with sender-proof mode off/observe, but required mode refuses
|
|
165
167
|
them without an additional correct proof implementation. The current sidecar attaches
|
|
166
168
|
proofs. A valid mint signature is not a signature over each provider request.
|
package/sdk/control.d.ts
CHANGED
|
@@ -95,6 +95,9 @@ export declare class ControlClient {
|
|
|
95
95
|
}[];
|
|
96
96
|
budget_tokens?: number | null;
|
|
97
97
|
budget_cents?: number | null;
|
|
98
|
+
/** Periodic spend limit: send both, or both null to remove it. */
|
|
99
|
+
budget_period?: "day" | "month" | null;
|
|
100
|
+
budget_period_cents?: number | null;
|
|
98
101
|
}, opts?: WriteOpts) => Promise<{
|
|
99
102
|
id: string;
|
|
100
103
|
}>;
|