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/cli/config.mjs CHANGED
@@ -205,7 +205,46 @@ export function assertConfigLoaded() {
205
205
  }
206
206
 
207
207
  export function resolveModel(provider) {
208
- return process.env.MODEL ?? defaultModelForProvider(provider);
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.PROVIDER ?? DEFAULT_PROVIDER;
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: trimSlash(process.env.PASSCONTROL_GATEWAY ?? DEFAULT_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: "llama-*",
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: "llama-3.3-70b-versatile",
20
+ groq: "openai/gpt-oss-20b",
21
21
  mistral: "mistral-small-latest",
22
- together: "openai/gpt-oss-20b",
23
- deepseek: "deepseek-chat",
24
- gemini: "gemini-2.5-flash",
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
  ],
@@ -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} npm install -g passcontrol@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
- headers: { accept: "application/vnd.npm.install-v1+json" },
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.9.4",
3
+ "version": "1.0.0",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
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@0.9.1 openai
12
- # or: npm install passcontrol@0.9.1 @anthropic-ai/sdk
13
+ npm install passcontrol openai
14
+ # or: npm install passcontrol @anthropic-ai/sdk
13
15
  ```
14
16
 
15
- Dependencies: only [`@noble/curves`](https://github.com/paulmillr/noble-curves) and the
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 developer API (`/api/control/v1`), authenticated with a `pc_` API key.
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
- ## 0.9.0 compatibility and assurance
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 in 0.9.0**. Its provider requests use
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
  }>;