probe-research 0.14.0 → 0.16.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.
Files changed (2) hide show
  1. package/bin/probe-research.js +355 -95
  2. package/package.json +2 -2
@@ -11,21 +11,29 @@
11
11
  * there is nothing here that can drift from the CLI's behaviour.
12
12
  *
13
13
  * Resolution order, best first:
14
- * 1. `probe` on PATH AND new enough -> exec it (the common re-run case)
14
+ * 1. `probe` on PATH at or above FIX_MIN -> exec it at once (the common re-run case)
15
15
  * 2. `uv` -> uvx, no install, no state left behind
16
- * 3. `pipx` -> isolated install
17
- * 4. bootstrap uv, then uvx -> the from-zero path
16
+ * 3. bootstrap uv, then uvx -> the from-zero path: uv at the Mac app's pin,
17
+ * its installer checked by sha256 before it runs
18
18
  *
19
19
  * We deliberately do NOT fall back to bare `pip install`: on a researcher's
20
20
  * machine that usually means a conda/system environment, and silently mutating
21
21
  * it to run an installer is exactly the kind of thing that breaks a training
22
22
  * run three days later.
23
+ *
24
+ * Windows: an install is refused before any of that (`isInstallCall`), with
25
+ * one PostHog event so we hear who asked (plan R17).
23
26
  */
24
27
 
25
28
  const { spawnSync } = require("node:child_process");
29
+ const crypto = require("node:crypto");
30
+ const fs = require("node:fs");
26
31
  const os = require("node:os");
32
+ const path = require("node:path");
27
33
 
28
34
  const DIST = "probe-research";
35
+ /** The compiled CLI `probe-research[all]` pins to its own version since the split (the CLI's `_entry.CLI_DIST`). */
36
+ const CLI_DIST = "probe-research-cli";
29
37
 
30
38
  /**
31
39
  * Where the published-version manifest lives. The SessionStart hook already
@@ -85,16 +93,58 @@ const MANIFEST_TIMEOUT_MS = 1500;
85
93
  * nothing, and there is no operator watching to read it. The old floor is
86
94
  * satisfied by every one of those installs.
87
95
  *
96
+ * (1) is why it is 0.374.0: the CLI's bootstrap (`probe service start
97
+ * --min-version`, plan T10) and an install that leaves a current Probe service.
98
+ * The floor only decides when the manifest's latest cannot be read; otherwise
99
+ * the launcher asks for the latest.
100
+ *
88
101
  * PUBLISHING ORDER MATTERS. `${DIST}>=${target}` must resolve, so this package
89
- * may only be `npm publish`ed once a CLI at or above the floor is live on PyPI.
90
- * That ordering is not enforced anywhere: the PyPI release is automated and
91
- * `npm publish` is manual, so it is a human who has to get it right. Raising
92
- * the floor ahead of the release strands the from-zero entry point.
102
+ * may only be published once a CLI at or above the floor is live on PyPI. The
103
+ * Release workflow (`release.yml`) publishes it after PyPI in the same run,
104
+ * automatically; raising the floor ahead of a CLI release strands the from-zero
105
+ * entry point, so the floor only ever names a release already on PyPI.
106
+ */
107
+ const MIN_CLI = "0.374.0";
108
+ /**
109
+ * The first CLI whose wizard opens the browser at once (instant sign-in, plan S8): its sign-in asks for
110
+ * the code before sending queued writes, and its setup runs behind the screens. An installed `probe` at
111
+ * or above it runs at once, with no manifest read: its own updater moves it forward. Below it (0.374.0
112
+ * to the release before this one still carry the slow wizard), the launcher runs that release's newest
113
+ * instead, downloaded once. Same rule as MIN_CLI: only ever a release already on PyPI.
114
+ */
115
+ const FIX_MIN = "0.385.0";
116
+ /**
117
+ * The floor where Probe's compiled CLI has no build (`getMissingBuild`): no release past
118
+ * the split installs there, so the newest that does is run as it is (plan R15, T22).
119
+ * 0.147.0 added the website's sign-in codes, which this launcher drops itself (`cliArgs`).
93
120
  */
94
- // 0.147.0 adds positional website sign-in codes to wizard/install. Publish this
95
- // launcher only after that CLI release is available on PyPI.
96
- const MIN_CLI = "0.147.0";
97
- const UV_INSTALL = "curl -LsSf https://astral.sh/uv/install.sh | sh";
121
+ const NO_BUILD_MIN_CLI = "0.147.0";
122
+
123
+ /** The uv this launcher installs where none is found: the Mac app's pin (desktop `wizard.rs` UV_VERSION). */
124
+ const UV_VERSION = "0.13.1";
125
+ /**
126
+ * The oldest uv on PATH the launcher runs (the desktop app's UV_MIN): 0.4.20 is the first that downloads
127
+ * CPython 3.13 final (PYTHON_REQUEST). Behind it, the pinned uv is installed and run by its path.
128
+ */
129
+ const UV_MIN = "0.4.20";
130
+ const UV_INSTALLER_URL = `https://astral.sh/uv/${UV_VERSION}/install.sh`;
131
+ /**
132
+ * sha256 of that installer script. It is saved to a private file and run only when it hashes
133
+ * to this: never `curl | sh`, which runs a truncated or tampered download. The script then
134
+ * checks the uv archive's own sha256 (where `sha256sum` exists).
135
+ */
136
+ const UV_INSTALLER_SHA256 = "7c482d409673a53f4d9bd34ae95c9166be3b8d89ca82f27dd7bca3cab457afff";
137
+ const UV_INSTALL = `curl -LsSf ${UV_INSTALLER_URL} | sh`;
138
+ /** How long the uv download may take. */
139
+ const UV_DOWNLOAD_TIMEOUT_S = 120;
140
+ /** How long `probe --version` may take before the installed `probe` counts as unknown. */
141
+ const VERSION_TIMEOUT_MS = 5000;
142
+ /**
143
+ * The Python `uv tool run` runs the CLI on (the CLI's `installs.PYTHON_REQUEST`, the desktop app's too).
144
+ * Left to choose, uv takes the first Python on PATH: Homebrew's 3.15 has no tiktoken wheel, so the
145
+ * install needed Rust (T19 smoke, 2026-11-03). uv downloads this one when the machine has none.
146
+ */
147
+ const PYTHON_REQUEST = "3.13";
98
148
 
99
149
  /** Compare dotted numeric versions. Returns true when `a` >= `b`. */
100
150
  function atLeast(a, b) {
@@ -108,6 +158,13 @@ function atLeast(a, b) {
108
158
  return true;
109
159
  }
110
160
 
161
+ /** The version `uv --version` answers, or null (none on PATH, no answer in time). */
162
+ function getUvVersion() {
163
+ const r = spawnSync("uv", ["--version"], { encoding: "utf8", shell: false, timeout: VERSION_TIMEOUT_MS });
164
+ const m = r.status === 0 && r.stdout ? r.stdout.match(/^uv (\d+(?:\.\d+)+)/) : null;
165
+ return m ? m[1] : null;
166
+ }
167
+
111
168
  /**
112
169
  * The version of an existing `probe`, or null if it cannot be determined.
113
170
  *
@@ -117,7 +174,7 @@ function atLeast(a, b) {
117
174
  * the wizard in it, which is precisely the bug this check exists to stop.
118
175
  */
119
176
  function installedVersion() {
120
- const r = spawnSync("probe", ["--version"], { encoding: "utf8", shell: false });
177
+ const r = spawnSync("probe", ["--version"], { encoding: "utf8", shell: false, timeout: VERSION_TIMEOUT_MS });
121
178
  if (r.status !== 0 || !r.stdout) return null;
122
179
  const m = r.stdout.match(/(\d+\.\d+\.\d+(?:\.\d+)?)/);
123
180
  return m ? m[1] : null;
@@ -156,7 +213,7 @@ function has(cmd) {
156
213
  // ONE shell string, never (command, args[], shell:true): Node deprecated that
157
214
  // pairing in DEP0190 because the args are concatenated rather than escaped,
158
215
  // and it printed a security warning on every single launcher run. `cmd` is a
159
- // literal at all three call sites, so there is nothing to escape here -- but
216
+ // literal at every call site, so there is nothing to escape here -- but
160
217
  // a warning users see on the from-zero entry point is its own problem.
161
218
  const line = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
162
219
  const r = spawnSync(line, { stdio: "ignore", shell: true });
@@ -191,46 +248,148 @@ const LauncherVerb = Object.freeze({
191
248
  });
192
249
  /** What `install` means -- exactly what `probe install` always ran (`main.py`). */
193
250
  const INSTALL_ACTION = Object.freeze(["--action", "configure"]);
194
- /** The website's one-time sign-in code; the CLI enforces the same shape. */
251
+ /** The website's retired one-time sign-in code; the CLI ignores the same shape. */
195
252
  const SIGN_IN_CODE = /^[A-Z0-9]{10}$/;
196
253
  /** The CLI root's own options: a call that starts with one names its own
197
254
  * command (`--base-url X doctor`, `--base-url=X doctor`) and reaches `probe`
198
255
  * untouched. */
199
256
  const ROOT_ONLY_FLAGS = Object.freeze(["--version", "--help", "--base-url", "--spool-dir", "--async", "--sync"]);
200
257
 
258
+ /** Where a retired sign-in code sits in what was typed (`CODE …`, `install CODE …`), or -1. */
259
+ function signInCodeAt(args) {
260
+ if (args.length && SIGN_IN_CODE.test(args[0])) return 0;
261
+ if (args[0] === LauncherVerb.INSTALL && args.length > 1 && SIGN_IN_CODE.test(args[1])) return 1;
262
+ return -1;
263
+ }
264
+
201
265
  /**
202
266
  * `probe` arguments for what was typed after `npx probe-research`.
203
267
  *
204
- * (nothing) -> wizard
205
- * CODE [flags] -> wizard CODE [flags]
206
- * install [CODE] [flags] -> wizard [CODE] --action configure [flags]
207
- * CODE install [flags] -> wizard CODE --action configure [flags]
268
+ * (nothing), CODE -> wizard
269
+ * install [CODE] [flags] -> wizard --action configure [flags]
270
+ * CODE install [flags] -> wizard --action configure [flags]
208
271
  * --flag ... -> wizard --flag ... (the CLI root's own excepted)
209
272
  * anything else -> unchanged (`doctor`, `backfill`, `wizard ...`)
210
273
  *
211
- * A sign-in code keeps its meaning either way: bare, it signs in and opens the
212
- * menu; with `install`, the one-time exchange waits for the agent selection so
213
- * it grants exactly what the user chose.
274
+ * A website sign-in code from an old copied command is dropped, never
275
+ * forwarded: no argv or `ps` listing carries it, and the browser approval
276
+ * signs in instead (install redesign R1).
214
277
  */
215
278
  function cliArgs(args) {
216
- const [first, ...rest] = args;
279
+ const at = signInCodeAt(args);
280
+ const words = at < 0 ? args : [...args.slice(0, at), ...args.slice(at + 1)];
281
+ const [first, ...rest] = words;
217
282
  if (first === undefined) return [LauncherVerb.WIZARD];
218
- if (SIGN_IN_CODE.test(first)) {
219
- if (rest[0] === LauncherVerb.INSTALL) {
220
- return [LauncherVerb.WIZARD, first, ...INSTALL_ACTION, ...rest.slice(1)];
221
- }
222
- return [LauncherVerb.WIZARD, first, ...rest];
223
- }
224
- if (first === LauncherVerb.INSTALL) {
225
- const code = rest.length && SIGN_IN_CODE.test(rest[0]) ? rest.slice(0, 1) : [];
226
- return [LauncherVerb.WIZARD, ...code, ...INSTALL_ACTION, ...rest.slice(code.length)];
227
- }
283
+ if (first === LauncherVerb.INSTALL) return [LauncherVerb.WIZARD, ...INSTALL_ACTION, ...rest];
228
284
  // Flags alone (`npx probe-research --agent codex`) used to reach the CLI's
229
285
  // root as `probe --agent codex`, which is not a command at all.
230
286
  if (first.startsWith("-") && !ROOT_ONLY_FLAGS.includes(first.split("=")[0])) {
231
- return [LauncherVerb.WIZARD, ...args];
287
+ return [LauncherVerb.WIZARD, ...words];
288
+ }
289
+ return words;
290
+ }
291
+
292
+ /** Said once when an old command passes a code; the CLI says the same words. */
293
+ const SIGN_IN_CODE_NOTE = "Sign-in codes are no longer needed; opening the browser instead.";
294
+
295
+ // --- Windows: no install (plan R17) ------------------------------------------
296
+
297
+ /** What a person on Windows reads; the CLI says the same words. */
298
+ const UNSUPPORTED_PLATFORM = "Probe runs on macOS and Linux for now.";
299
+ /** The wizard actions that install or sign in: refused on Windows, before any download. */
300
+ const INSTALL_ACTIONS = Object.freeze(["configure", "login"]);
301
+
302
+ /** Whether `probe` arguments install or sign in (`install`, `--action configure|login`). */
303
+ function isInstallCall(forwarded) {
304
+ if (forwarded[0] !== LauncherVerb.WIZARD) return false;
305
+ for (let i = 1; i < forwarded.length; i++) {
306
+ const word = forwarded[i];
307
+ if (word === "--action") return INSTALL_ACTIONS.includes(forwarded[i + 1]);
308
+ if (word.startsWith("--action=")) return INSTALL_ACTIONS.includes(word.slice("--action=".length));
309
+ }
310
+ return false;
311
+ }
312
+
313
+ /** The CLI's PostHog project and host (`analytics/core.py`; agent/tests holds the two in step). */
314
+ const POSTHOG_HOST = "https://us.i.posthog.com";
315
+ const POSTHOG_KEY = "phc_pCSs24bQtPaxoJ59PaTtTpJDS3dfzymfZeY74XQQ956K";
316
+ /** The catalog's name (contracts/probe_contracts/analytics/events.json). */
317
+ const UNSUPPORTED_EVENT = "install.unsupported_platform";
318
+ /** The event's `os` as the dashboard and the CLI send it. */
319
+ const OS_NAMES = Object.freeze({ win32: "windows" });
320
+ /** How long the refusal may wait on PostHog before it exits anyway. */
321
+ const TELEMETRY_TIMEOUT_MS = 1500;
322
+ /** `PROBE_TELEMETRY` spellings that turn telemetry off, as the CLI reads them. */
323
+ const TELEMETRY_OFF = Object.freeze(["off", "0", "false", "no", "disabled"]);
324
+
325
+ /** Whether this run may send the event: the CLI's switch, DO_NOT_TRACK, and hosted servers only. */
326
+ function maySendTelemetry(env) {
327
+ if (TELEMETRY_OFF.includes(String(env.PROBE_TELEMETRY || "").trim().toLowerCase())) return false;
328
+ if (String(env.DO_NOT_TRACK || "").trim() === "1") return false;
329
+ if (!env.PROBE_BASE_URL) return true;
330
+ // A self-hosted server's people are never reported to us (the CLI's `hosted_base_url`).
331
+ try {
332
+ const url = new URL(env.PROBE_BASE_URL);
333
+ const host = url.hostname.toLowerCase().replace(/\.$/, "");
334
+ return url.protocol === "https:" && (host === "prbe.ai" || host.endsWith(".prbe.ai"));
335
+ } catch {
336
+ return false;
232
337
  }
233
- return args;
338
+ }
339
+
340
+ /** The CLI's anonymous machine id (`analytics/core.py` `machine_id`), minted the same way when absent. */
341
+ function machineId(env) {
342
+ const home = env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
343
+ const file = path.join(home, "probe-telemetry", "machine_id");
344
+ try {
345
+ const found = fs.readFileSync(file, "utf8").trim();
346
+ if (found) return found;
347
+ } catch {}
348
+ const minted = crypto.randomUUID().replace(/-/g, "");
349
+ try {
350
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
351
+ fs.writeFileSync(file, minted, { flag: "wx", mode: 0o600 });
352
+ } catch {
353
+ try {
354
+ return fs.readFileSync(file, "utf8").trim() || minted; // another process minted it first
355
+ } catch {}
356
+ }
357
+ return minted;
358
+ }
359
+
360
+ /** POST one `install.unsupported_platform`, awaited and bounded; never throws. */
361
+ async function sendUnsupportedPlatform(env) {
362
+ if (!maySendTelemetry(env)) return;
363
+ try {
364
+ const machine = machineId(env);
365
+ const host = (env.PROBE_TELEMETRY_HOST || POSTHOG_HOST).replace(/\/+$/, "");
366
+ const version = require("../package.json").version;
367
+ await fetch(`${host}/batch/`, {
368
+ method: "POST",
369
+ signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS),
370
+ headers: { "content-type": "application/json" },
371
+ body: JSON.stringify({
372
+ api_key: POSTHOG_KEY,
373
+ batch: [{
374
+ event: UNSUPPORTED_EVENT,
375
+ distinct_id: `machine:${machine}`,
376
+ timestamp: new Date().toISOString(),
377
+ properties: {
378
+ surface: "launcher",
379
+ os: OS_NAMES[process.platform] || process.platform,
380
+ arch: process.arch,
381
+ client_version: version,
382
+ client_kind: "launcher",
383
+ machine_id: machine,
384
+ authenticated: false,
385
+ $process_person_profile: false,
386
+ $lib: "probe-research-launcher",
387
+ $lib_version: version,
388
+ },
389
+ }],
390
+ }),
391
+ });
392
+ } catch {}
234
393
  }
235
394
 
236
395
  /**
@@ -256,6 +415,35 @@ function uvRunFlags(forwarded) {
256
415
  return mayUseInstalled(forwarded) ? [] : ["--isolated"];
257
416
  }
258
417
 
418
+ /**
419
+ * What this computer is, when Probe's compiled CLI (probe-research-cli) has no build for it;
420
+ * null when it has one: macOS arm64 and x86_64, Linux with glibc 2.28+ on x86_64 and aarch64 (the
421
+ * active platforms of agent/packaging/private/platforms/platforms.json; the test holds the two together).
422
+ * Anywhere else `probe-research[all]` at a newer release cannot install, so the launcher says so
423
+ * and asks for the newest release that installs here. Windows is dormant: its last build is 0.372.0.
424
+ */
425
+ function getMissingBuild(platform, arch, glibc) {
426
+ if (platform === "darwin" && (arch === "arm64" || arch === "x64")) return null;
427
+ if (platform === "win32") return `win32 ${arch}: Windows is not supported yet`;
428
+ // manylinux_2_28: glibc 2.28 or newer.
429
+ const [major, minor] = String(glibc || "0.0").split(".").map(Number);
430
+ const hasGlibc228 = major > 2 || (major === 2 && minor >= 28);
431
+ if (platform === "linux" && (arch === "x64" || arch === "arm64") && hasGlibc228) return null;
432
+ const libc = platform === "linux" ? (glibc ? `glibc ${glibc}` : "musl") : "";
433
+ return [platform, arch, libc].filter(Boolean).join(" ");
434
+ }
435
+
436
+ /** The C library's version on Linux; none on musl (node reports no glibc there). */
437
+ function readGlibc() {
438
+ try {
439
+ // No socket list: it would look up every open socket's name (slow on a slow resolver).
440
+ process.report.excludeNetwork = true;
441
+ return process.report.getReport().header.glibcVersionRuntime || null;
442
+ } catch {
443
+ return null;
444
+ }
445
+ }
446
+
259
447
  /** What a repair says when the newest release cannot be read. */
260
448
  const REPAIR_NEEDS_NETWORK = "probe repair needs the network to fetch a working CLI";
261
449
 
@@ -264,18 +452,29 @@ async function main() {
264
452
  // `npx probe-research` with no arguments runs the wizard — that is the entire
265
453
  // reason this package exists, so it should not require remembering a verb.
266
454
  const forwarded = cliArgs(args);
267
- const wanted = MIN_CLI;
268
-
269
- // Hand off to an existing install only when it is BOTH above the floor and
270
- // current. The floor alone is not enough, and that was the bug: `npx <tool>`
271
- // means "run the latest", but a floor is satisfied forever, so anyone who had
272
- // ever installed the CLI was frozen on it and npx silently never delivered
273
- // another update.
274
- //
275
- // That is the same failure the `--refresh` flag below exists to fix -- uv
276
- // serving whatever it resolved on day one -- in the other branch. It was
277
- // fixed there and left standing here.
455
+ // FIRST, before any `probe` or uv is looked for: an installed one would
456
+ // otherwise run the install (plan R28).
457
+ if (process.platform === "win32" && isInstallCall(forwarded)) {
458
+ console.error(UNSUPPORTED_PLATFORM);
459
+ await sendUnsupportedPlatform(process.env);
460
+ process.exit(1);
461
+ }
462
+ if (signInCodeAt(args) >= 0) console.error(SIGN_IN_CODE_NOTE);
463
+
464
+ // Hand off to an installed CLI at or above FIX_MIN at once, with no manifest
465
+ // read before the wizard: such a CLI keeps itself current (its updater), so a
466
+ // floor no longer freezes anyone on an old release the way it did before the
467
+ // CLI updated itself. Below FIX_MIN, the published latest is fetched instead.
468
+ // No compiled CLI build for this computer: no release after the split installs here, so an
469
+ // installed probe is never "behind" one; run it as long as it is above the floor.
470
+ const missingBuild = getMissingBuild(process.platform, process.arch,
471
+ process.platform === "linux" ? readGlibc() : null);
472
+ const wanted = missingBuild ? NO_BUILD_MIN_CLI : MIN_CLI;
278
473
  let latest = null;
474
+ if (missingBuild && mayUseInstalled(forwarded) && has("probe")) {
475
+ const found = installedVersion();
476
+ if (found && atLeast(found, wanted)) return run("probe", forwarded);
477
+ }
279
478
  if (!mayUseInstalled(forwarded)) {
280
479
  // A repair runs the NEWEST release, never the floor: the floor predates
281
480
  // `probe repair`, and would hand the job to a CLI that cannot do it.
@@ -286,75 +485,136 @@ async function main() {
286
485
  }
287
486
  } else if (has("probe")) {
288
487
  const found = installedVersion();
289
- if (found && atLeast(found, wanted)) {
290
- latest = await latestVersion();
291
- // Unknown latest means run what we have: see latestVersion's contract.
292
- if (!latest || atLeast(found, latest)) return run("probe", forwarded);
293
- console.error(
294
- `probe-research: probe ${found} is behind ${latest}; fetching the latest…`,
295
- );
296
- } else {
297
- console.error(
298
- `probe-research: installed probe ${found || "(unknown version)"} is older than ` +
299
- `${wanted}; fetching the latest…`,
300
- );
301
- }
488
+ // A fixed CLI runs at once (plan S8): no manifest read on the way to the browser.
489
+ if (found && atLeast(found, FIX_MIN)) return run("probe", forwarded);
490
+ latest = await latestVersion();
491
+ // Unknown latest (offline, no route) means run what we have: see latestVersion's contract.
492
+ if (!latest && found && atLeast(found, wanted)) return run("probe", forwarded);
493
+ console.error(
494
+ `probe-research: installed probe ${found || "(unknown version)"} is older than ` +
495
+ `${FIX_MIN}; fetching ${latest || "the latest"}…`,
496
+ );
497
+ } else {
498
+ latest = await latestVersion();
302
499
  }
303
- // A FLOOR, not an exact pin. Unpinned, `uv tool run --from probe-research`
304
- // reuses an already-installed 0.8.2 tool; pinned exactly, it demands a PyPI
305
- // version that may not exist. `>=` fixes both.
306
- // Resolve to the newest version we actually know about, not merely the floor.
307
- // `uv tool run` reuses an installed tool that satisfies the constraint, so a
308
- // stale 0.46.0 satisfies `>=0.36.0` and uv hands back the very version we
309
- // just decided was out of date -- the currency check above would print
310
- // "fetching the latest" and then change nothing. Measured exactly that before
311
- // this line existed.
500
+ // The published latest, pinned exactly (plan S8): the manifest names it only once it is on PyPI, and
501
+ // uv reuses the env it built for that version, so it is downloaded once, ever. A range let uv hand back
502
+ // the stale tool it already had (a 0.46.0 satisfied `>=0.36.0`: measured). Unknown latest (offline, no
503
+ // route): any fixed CLI uv already has, `>=FIX_MIN`. A repair still asks for the newest, `>=`.
504
+ const pinned = !missingBuild && latest && atLeast(latest, FIX_MIN) ? latest : null;
312
505
  const target = latest && atLeast(latest, wanted) ? latest : wanted;
313
506
  // `[all]`: the CLI's dependencies are an extra from the release after
314
507
  // 0.188 (plan 2.11); asking for it is harmless while core still has them.
315
- const spec = `${DIST}[all]>=${target}`;
316
- // REFRESH. uv caches the ENVIRONMENT it built for a requirement, so a range
317
- // like `>=0.10.0` keeps serving whatever it resolved the FIRST time — every
318
- // user frozen on the version they happened to run on day one, with the
319
- // launcher silently never delivering another update.
320
- //
321
- // It has to be the full `--refresh`: `--refresh-package` only refreshes
322
- // package METADATA and still reuses the built environment (measured — it
323
- // kept returning 0.10.0 after 0.10.1 was published). The full refresh costs
324
- // ~100ms, which is nothing for a command that only runs when there is no
325
- // usable local install.
326
- const isolated = uvRunFlags(forwarded);
327
- if (has("uv")) {
328
- return run("uv", ["tool", "run", ...isolated, "--refresh", "--from", spec, "probe", ...forwarded]);
508
+ // It is also what brings the compiled CLI (probe-research-cli) since the split.
509
+ if (missingBuild) {
510
+ console.error(
511
+ `probe-research: Probe's CLI has no build for this computer (${missingBuild}); installing ` +
512
+ "the newest release that runs here, which will not update itself. The Python SDK alone " +
513
+ "(the probe-research package without [all]) installs at every version.",
514
+ );
329
515
  }
330
- if (has("pipx")) {
331
- return run("pipx", ["run", "--no-cache", "--spec", spec, "probe", ...forwarded]);
516
+ const spec = missingBuild ? `${DIST}[all]`
517
+ : !mayUseInstalled(forwarded) ? `${DIST}[all]>=${target}`
518
+ : pinned ? `${DIST}[all]==${pinned}` : `${DIST}[all]>=${FIX_MIN}`;
519
+ // No pipx: the CLI installs itself for good with uv only, so a pipx run ended
520
+ // in that refusal anyway (install redesign R11). Cache flags: getRefreshFlags.
521
+ const isolated = uvRunFlags(forwarded);
522
+ const refresh = getRefreshFlags({ repair: !mayUseInstalled(forwarded), missingBuild, pinned });
523
+ const uvOnPath = has("uv");
524
+ const uvVersion = uvOnPath ? getUvVersion() : null;
525
+ if (uvVersion && atLeast(uvVersion, UV_MIN)) {
526
+ return run("uv", ["tool", "run", ...isolated, "--python", PYTHON_REQUEST, ...refresh, "--from", spec, "probe",
527
+ ...forwarded]);
332
528
  }
333
529
 
334
530
  if (process.platform === "win32") {
335
531
  console.error(
336
- `probe-research: needs uv or pipx on PATH.\n` +
532
+ `probe-research: needs uv ${UV_MIN} or newer on PATH.\n` +
337
533
  ` Install uv: https://docs.astral.sh/uv/getting-started/installation/`,
338
534
  );
339
535
  process.exit(1);
340
536
  }
341
537
 
342
- console.error("probe-research: installing uv (one-time)…");
343
- const boot = spawnSync("sh", ["-c", UV_INSTALL], { stdio: "inherit" });
344
- if (boot.status !== 0) {
345
- console.error(
346
- `probe-research: could not install uv automatically.\n Run: ${UV_INSTALL}`,
347
- );
348
- process.exit(1);
538
+ if (uvOnPath) {
539
+ console.error(`probe-research: ${uvVersion ? `uv ${uvVersion} is older than ${UV_MIN}` : "uv on PATH did not say its version"}.`);
349
540
  }
350
- // The installer drops uv in ~/.local/bin, which is not on THIS process's PATH
351
- // because it was resolved before the install ran.
352
- const uv = `${os.homedir()}/.local/bin/uv`;
541
+ const uv = installUv(process.env, forwarded);
353
542
  return run(uv, [
354
- "tool", "run", ...isolated, "--refresh", "--from", spec, "probe", ...forwarded,
543
+ "tool", "run", ...isolated, "--python", PYTHON_REQUEST, ...refresh, "--from", spec, "probe", ...forwarded,
355
544
  ]);
356
545
  }
357
546
 
547
+ /**
548
+ * uv's cache flags for a throwaway run. A pinned release builds once and is reused from uv's cache:
549
+ * `--refresh-package` reads only probe-research's index again (and the compiled CLI's, which `[all]` pins
550
+ * to the same version), so a release newer than uv's 10-minute copy still resolves, and no cached wheel
551
+ * or env is fetched again. A range (a repair's newest,
552
+ * a computer with no compiled build) needs the full `--refresh`: uv reuses the env it built for a range,
553
+ * so `--refresh-package` alone kept serving 0.10.0 after 0.10.1 shipped (measured).
554
+ */
555
+ function getRefreshFlags({ repair, missingBuild, pinned }) {
556
+ if (repair || missingBuild) return ["--refresh"];
557
+ return pinned ? ["--refresh-package", DIST, "--refresh-package", CLI_DIST] : [];
558
+ }
559
+
560
+ /** The hex sha256 of a file's bytes. */
561
+ function hashFile(file) {
562
+ return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
563
+ }
564
+
565
+ /**
566
+ * Where uv's installer puts uv, in its own order (UV_INSTALL_DIR, XDG_BIN_HOME,
567
+ * XDG_DATA_HOME/../bin, ~/.local/bin): none of them is on THIS process's PATH,
568
+ * which was read before the install ran.
569
+ */
570
+ function getInstalledUvPath(env) {
571
+ const folders = [env.UV_INSTALL_DIR, env.XDG_BIN_HOME,
572
+ env.XDG_DATA_HOME ? path.join(env.XDG_DATA_HOME, "..", "bin") : null,
573
+ path.join(os.homedir(), ".local", "bin")];
574
+ for (const folder of folders.filter(Boolean)) {
575
+ const candidate = path.join(folder, "uv");
576
+ try {
577
+ fs.accessSync(candidate, fs.constants.X_OK);
578
+ return candidate;
579
+ } catch {}
580
+ }
581
+ return null;
582
+ }
583
+
584
+ /**
585
+ * Install uv UV_VERSION: its installer downloaded into a private folder, run with `sh` only
586
+ * when it hashes to UV_INSTALLER_SHA256, the folder removed after. The uv it installed, or
587
+ * exit 1 with the command to run by hand. With `--json` in `forwarded`, stdout carries only
588
+ * the CLI's events, so the installer's own text goes to stderr.
589
+ */
590
+ function installUv(env, forwarded = []) {
591
+ console.error(`probe-research: installing uv ${UV_VERSION} (one-time)…`);
592
+ const folder = fs.mkdtempSync(path.join(os.tmpdir(), "probe-uv-"));
593
+ const script = path.join(folder, "install.sh");
594
+ let failure = null;
595
+ try {
596
+ const fetched = spawnSync("curl", ["-fsSL", "--max-time", String(UV_DOWNLOAD_TIMEOUT_S), "-o", script,
597
+ UV_INSTALLER_URL], { stdio: ["ignore", "inherit", "inherit"] });
598
+ if (fetched.status !== 0) {
599
+ failure = `could not download the uv installer (${fetched.error ? fetched.error.message : `curl exit ${fetched.status}`})`;
600
+ } else if (hashFile(script) !== UV_INSTALLER_SHA256) {
601
+ failure = "the downloaded uv installer is not the one this launcher pins (sha256 mismatch); it was not run";
602
+ } else {
603
+ const ran = spawnSync("sh", [script], { stdio: ["inherit", forwarded.includes("--json") ? 2 : "inherit", "inherit"] });
604
+ if (ran.status !== 0) failure = `the uv installer failed (exit ${ran.status === null ? "signal" : ran.status})`;
605
+ }
606
+ } finally {
607
+ fs.rmSync(folder, { recursive: true, force: true });
608
+ }
609
+ const uv = failure ? null : getInstalledUvPath(env);
610
+ if (!uv) {
611
+ console.error(`probe-research: ${failure || "the uv installer finished, but no uv is where it installs"}.\n` +
612
+ ` Run: ${UV_INSTALL}`);
613
+ process.exit(1);
614
+ }
615
+ return uv;
616
+ }
617
+
358
618
  main().catch((err) => {
359
619
  // A throw here would exit 0 under an unhandled rejection on some Node builds,
360
620
  // which reads as success to whatever invoked the launcher.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "probe-research",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "description": "Setup wizard for Probe Research in your coding agents. Runs from zero with npx.",
5
5
  "bin": {
6
6
  "probe-research": "bin/probe-research.js"
@@ -14,7 +14,7 @@
14
14
  "license": "Apache-2.0",
15
15
  "repository": {
16
16
  "type": "git",
17
- "url": "git+https://github.com/prbe-ai/research-os-agent.git"
17
+ "url": "git+https://github.com/prbe-ai/research-os.git"
18
18
  },
19
19
  "homepage": "https://research.prbe.ai/connect",
20
20
  "keywords": [