probe-research 0.25.0 → 0.26.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.
@@ -281,13 +281,26 @@ function run(cmd, args) {
281
281
  // stdio inherit is load-bearing: the wizard is INTERACTIVE (arrow-key menu)
282
282
  // and opens a browser. Capturing its output would break both.
283
283
  const r = spawnSync(cmd, args, { stdio: "inherit", shell: false });
284
- if (r.error) {
285
- console.error(`probe-research: could not run ${cmd}: ${r.error.message}`);
286
- process.exit(1);
287
- }
284
+ if (r.error) exitWithFailure(`could not run ${cmd}: ${r.error.message}`);
288
285
  process.exit(r.status === null ? 1 : r.status);
289
286
  }
290
287
 
288
+ /** Whether a call answers in JSON: `--json` among its own words, before any `--` (as the `probe` shim reads it). */
289
+ function isJsonCall(args) {
290
+ const own = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
291
+ return own.includes("--json");
292
+ }
293
+
294
+ /**
295
+ * The launcher's own failure, exit 1: its line on stderr, and for a JSON call the answer too (`incomplete`),
296
+ * so an agent's command never ends without one (D97). `args`: what was typed after `npx probe-research`.
297
+ */
298
+ function exitWithFailure(message, args = process.argv.slice(2)) {
299
+ console.error(`probe-research: ${message}`);
300
+ if (isJsonCall(args)) agentRun.refuse(agentRun.Reason.INCOMPLETE, message, 1);
301
+ process.exit(1);
302
+ }
303
+
291
304
  /**
292
305
  * The words the launcher itself interprets. Everything else is a CLI command of
293
306
  * its own and is forwarded untouched.
@@ -431,6 +444,14 @@ async function sendUnsupportedPlatform(env) {
431
444
  await sendLauncherEvent(env, UNSUPPORTED_EVENT);
432
445
  }
433
446
 
447
+ /** Windows asked to install or sign in (plan R17): the words, the event, and for a JSON call the answer; exit 1. */
448
+ async function refuseWindows(args) {
449
+ console.error(UNSUPPORTED_PLATFORM);
450
+ await sendUnsupportedPlatform(process.env);
451
+ if (isJsonCall(args)) agentRun.refuse(agentRun.Reason.INCOMPLETE, UNSUPPORTED_PLATFORM, 1);
452
+ process.exit(1);
453
+ }
454
+
434
455
  /** The install prompt's first funnel step (plan D14), sent by the launcher before any CLI exists. */
435
456
  const SIGN_IN_STARTED_EVENT = "agent_install.signin_started";
436
457
 
@@ -597,11 +618,7 @@ async function main() {
597
618
  const forwarded = cliArgs(args);
598
619
  // FIRST, before any `probe` or uv is looked for: an installed one would
599
620
  // otherwise run the install (plan R28).
600
- if (process.platform === "win32" && isInstallCall(forwarded)) {
601
- console.error(UNSUPPORTED_PLATFORM);
602
- await sendUnsupportedPlatform(process.env);
603
- process.exit(1);
604
- }
621
+ if (process.platform === "win32" && isInstallCall(forwarded)) await refuseWindows(args);
605
622
  if (signInCodeAt(args) >= 0) console.error(SIGN_IN_CODE_NOTE);
606
623
  if (isStatusJson(forwarded) && getProbeCommands().length === 0) {
607
624
  // No Probe here: the install prompt's first read (step 1b) answers at once, with no download (D37).
@@ -609,7 +626,7 @@ async function main() {
609
626
  // A saved sign-in with no CLI is Probe here too: the CLI first, then its status, never `none` (F4).
610
627
  // Windows has no CLI build: a sign-in the SDK saved there is no install to read.
611
628
  if (process.platform === "win32" || !signIn.hasSavedSignIn(process.env)) {
612
- agentRun.answer({ v: 1, setup: NONE_SETUP }, 0);
629
+ agentRun.answerRead({ setup: NONE_SETUP }, 0);
613
630
  }
614
631
  return runAgentCall(await getAgentProbe(startedMs, AgentStep.STATUS), forwarded, startedMs, AgentStep.STATUS);
615
632
  }
@@ -643,10 +660,7 @@ async function main() {
643
660
  // A repair runs the NEWEST release, never the floor: the floor predates
644
661
  // `probe repair`, and would hand the job to a CLI that cannot do it.
645
662
  latest = await latestVersion();
646
- if (!latest) {
647
- console.error(`probe-research: ${REPAIR_NEEDS_NETWORK}`);
648
- process.exit(1);
649
- }
663
+ if (!latest) exitWithFailure(REPAIR_NEEDS_NETWORK);
650
664
  } else if (has("probe")) {
651
665
  const found = installedVersion();
652
666
  // A fixed CLI runs at once (plan S8): no manifest read on the way to the browser.
@@ -692,11 +706,8 @@ async function main() {
692
706
  }
693
707
 
694
708
  if (process.platform === "win32") {
695
- console.error(
696
- `probe-research: needs uv ${UV_MIN} or newer on PATH.\n` +
697
- ` Install uv: https://docs.astral.sh/uv/getting-started/installation/`,
698
- );
699
- process.exit(1);
709
+ exitWithFailure(`needs uv ${UV_MIN} or newer on PATH.\n` +
710
+ " Install uv: https://docs.astral.sh/uv/getting-started/installation/");
700
711
  }
701
712
 
702
713
  if (uvOnPath) {
@@ -909,11 +920,7 @@ async function runSignIn(rest, startedMs) {
909
920
  const deadlineMs = startedMs + agentRun.AGENT_BUDGET_MS;
910
921
  const unknown = rest.find((word) => !SIGN_IN_FLAGS.includes(word));
911
922
  if (unknown) await refuseAgent(AgentStep.SIGN_IN, agentRun.Reason.INCOMPLETE, `sign-in takes ${SIGN_IN_FLAGS.join(", ")}, not ${unknown}`, 2);
912
- if (process.platform === "win32") {
913
- console.error(UNSUPPORTED_PLATFORM);
914
- await sendUnsupportedPlatform(process.env);
915
- process.exit(1);
916
- }
923
+ if (process.platform === "win32") await refuseWindows(rest);
917
924
  const hosted = signIn.findHostedAgent(process.env);
918
925
  if (hosted) {
919
926
  await refuseAgent(AgentStep.SIGN_IN, agentRun.Reason.HOSTED_AGENT, `This chat runs in ${hosted}, not on your `
@@ -1105,9 +1112,8 @@ function installUv(env, forwarded = []) {
1105
1112
  }
1106
1113
  const uv = failure ? null : getInstalledUvPath(env);
1107
1114
  if (!uv) {
1108
- console.error(`probe-research: ${failure || "the uv installer finished, but no uv is where it installs"}.\n` +
1109
- ` Run: ${UV_INSTALL}`);
1110
- process.exit(1);
1115
+ exitWithFailure(`${failure || "the uv installer finished, but no uv is where it installs"}.\n Run: ${UV_INSTALL}`,
1116
+ forwarded);
1111
1117
  }
1112
1118
  return uv;
1113
1119
  }
@@ -1115,6 +1121,5 @@ function installUv(env, forwarded = []) {
1115
1121
  main().catch((err) => {
1116
1122
  // A throw here would exit 0 under an unhandled rejection on some Node builds,
1117
1123
  // which reads as success to whatever invoked the launcher.
1118
- console.error(`probe-research: ${err && err.message ? err.message : err}`);
1119
- process.exit(1);
1124
+ exitWithFailure(String(err && err.message ? err.message : err));
1120
1125
  });
package/lib/agent-run.js CHANGED
@@ -5,8 +5,9 @@
5
5
  * deadline, SIGKILL 5 s later, then one JSON line saying to run it again. Never the interactive
6
6
  * wizard: a detached group loses the terminal.
7
7
  *
8
- * Every answer the launcher gives itself is one JSON line, `{ok, reason, message?}`, with a reason
9
- * from the CLI's closed list (`probe.core.events.AgentInstallReason`): the agent branches on it.
8
+ * One output rule for every agent command (D97): JSON lines on stdout, the last one the answer. The
9
+ * launcher's own answer is the CLI's `done` event, `{v, event: "done", ok, reason, exit_code, ...}`, its
10
+ * reason from the CLI's closed list (`probe.core.events.AgentInstallReason`): the agent branches on it.
10
11
  */
11
12
 
12
13
  const fs = require("node:fs");
@@ -35,14 +36,32 @@ const Reason = Object.freeze({
35
36
  });
36
37
  /** Exit statuses: 75 means "run the same command again" (the CLI's `AGENT_EXIT_CODES`). */
37
38
  const EXIT_AGAIN = 75;
39
+ /** Every line's `v` (`probe.core.events.SCHEMA_VERSION`). */
40
+ const SCHEMA_VERSION = 1;
41
+ /** A line's `event`: the answer is the CLI's `done` (`probe.core.events.Event`); a line before it, `progress`. */
42
+ const Event = Object.freeze({ DONE: "done", PROGRESS: "progress" });
38
43
 
39
- /** One JSON answer on stdout, then exit `code`. Written synchronously: on a macOS pipe
40
- * `process.stdout` is asynchronous, and `process.exit` would drop the line it still queues. */
44
+ /** The answer, a `done` event (`say`, the line the agent shows, right after `v` and `event`), on stdout, then
45
+ * exit `code`. Written synchronously: on a macOS pipe `process.stdout` is asynchronous, and `process.exit`
46
+ * would drop the line it still queues. */
41
47
  function answer(fields, code) {
42
- writeLine(JSON.stringify(fields));
48
+ const say = typeof fields.say === "string" ? { say: fields.say } : {};
49
+ writeLine(JSON.stringify({ v: SCHEMA_VERSION, event: Event.DONE, ...say, ok: code === 0, reason: null, ...fields,
50
+ exit_code: code }));
43
51
  process.exit(code);
44
52
  }
45
53
 
54
+ /** A read's answer (`status --json` with no Probe here): one object in the CLI read's own shape, no `event`. */
55
+ function answerRead(fields, code) {
56
+ writeLine(JSON.stringify({ v: SCHEMA_VERSION, ...fields }));
57
+ process.exit(code);
58
+ }
59
+
60
+ /** One `progress` line (`say`: what the agent shows as it comes): never the answer, which stays last. */
61
+ function toProgressLine(fields) {
62
+ return JSON.stringify({ v: SCHEMA_VERSION, event: Event.PROGRESS, ...fields });
63
+ }
64
+
46
65
  /** One line on stdout, written before this returns (a full pipe falls back to the stream). */
47
66
  function writeLine(text) {
48
67
  try {
@@ -52,7 +71,7 @@ function writeLine(text) {
52
71
  }
53
72
  }
54
73
 
55
- /** Exit with `code` after one `{ok: false, reason, message}` line. */
74
+ /** Exit with `code` after the answer `{ok: false, reason, message}`. */
56
75
  function refuse(reason, message, code, extra = {}) {
57
76
  answer({ ok: false, reason, message, ...extra }, code);
58
77
  }
@@ -109,10 +128,14 @@ module.exports = {
109
128
  CLI_MARGIN_MS,
110
129
  DEADLINE_ENV,
111
130
  EXIT_AGAIN,
131
+ Event,
112
132
  KILL_GRACE_MS,
113
133
  Reason,
134
+ SCHEMA_VERSION,
114
135
  answer,
136
+ answerRead,
115
137
  refuse,
116
138
  runWithBackstop,
139
+ toProgressLine,
117
140
  writeLine,
118
141
  };
@@ -9,7 +9,7 @@
9
9
  const fs = require("node:fs");
10
10
  const path = require("node:path");
11
11
 
12
- const { writeLine } = require("./agent-run");
12
+ const { toProgressLine, writeLine } = require("./agent-run");
13
13
  const { DownloadStage } = require("./background-download");
14
14
  const { ApprovalStatus, fetchApproval, getStateFolder } = require("./sign-in");
15
15
 
@@ -21,8 +21,6 @@ const STAGE_WORDS = Object.freeze({
21
21
  [InstallStage.STARTING]: "Probe is still installing on this computer: starting its service for the first time.",
22
22
  [InstallStage.DONE]: "Probe is installed on this computer: done.",
23
23
  });
24
- /** A progress line's `event`: it is never the answer, which stays the last line (and has `ok`). */
25
- const PROGRESS_EVENT = "progress";
26
24
  /** The shortest gap between two reads; the server's poll interval when longer. */
27
25
  const MIN_READ_GAP_MS = 2000;
28
26
  /** This attempt's approval and the last stage said, kept for its next `sign-in --wait` (0600, no secret). */
@@ -108,8 +106,8 @@ class ApprovalWatch {
108
106
  }
109
107
  if (this.isApproved() && stage && stage !== this.reportedStage) {
110
108
  this.markSaid(stage);
111
- this.write(JSON.stringify({ event: PROGRESS_EVENT, say: getApprovedSay(this.account, stage), approved: true,
112
- account: this.account, stage }));
109
+ this.write(toProgressLine({ say: getApprovedSay(this.account, stage), approved: true, account: this.account,
110
+ stage }));
113
111
  }
114
112
  if (isNew) saveApproval(this.pending.attempt, this.account, this.reportedStage);
115
113
  return false;
@@ -147,4 +145,4 @@ class ApprovalWatch {
147
145
  }
148
146
  }
149
147
 
150
- module.exports = { APPROVAL_NAME, ApprovalWatch, InstallStage, PROGRESS_EVENT, getApprovedSay };
148
+ module.exports = { APPROVAL_NAME, ApprovalWatch, InstallStage, getApprovedSay };
@@ -6,6 +6,8 @@
6
6
 
7
7
  const { spawnSync } = require("node:child_process");
8
8
 
9
+ const { getSignInBase } = require("./sign-in");
10
+
9
11
  /** What install.md's first step ran before: the same status, with the same flags. */
10
12
  const STATUS_ARGS = Object.freeze(["status", "--json", "--refresh"]);
11
13
  /** Status's answer is ~25 KB on a computer with every agent set up; past spawnSync's 1 MB default it would be cut. */
@@ -13,6 +15,9 @@ const MAX_ANSWER_BYTES = 16 * 1024 * 1024;
13
15
 
14
16
  /** `setup.why`'s word for "no saved sign-in" (the CLI's `SetupGap.SIGNED_OUT`). */
15
17
  const SIGNED_OUT_GAP = "signed_out";
18
+ /** `setup.why`'s word for an account check with no answer in time (the CLI's `SetupGap.CREDENTIAL_UNCHECKED`):
19
+ * said alone only when nothing is missing on this computer. */
20
+ const UNCHECKED_GAP = "credential_unchecked";
16
21
 
17
22
  /** What the status said about signing in here. */
18
23
  const SetupCheck = Object.freeze({
@@ -20,17 +25,44 @@ const SetupCheck = Object.freeze({
20
25
  SET_UP: "set_up",
21
26
  /** The status refused (`ok: false` with a `reason`): answer it, so the agent acts on its reason. */
22
27
  REFUSED: "refused",
23
- /** Anything else (none, partial signed out, unknown, an older CLI with no `setup`): sign in. */
28
+ /** Anything else (none, partial signed out, any other unknown, an older CLI with no `setup`): sign in. */
24
29
  NOT_SET_UP: "not_set_up",
25
30
  /** The status did not answer before `deadlineMs`. */
26
31
  TIMED_OUT: "timed_out",
27
32
  });
28
33
 
29
- /** install.md's rule for the re-paste menu: `done`, or `partial` still signed in (PR23b, P3: a plugin off). */
30
- function isSetUp(setup) {
34
+ /**
35
+ * Whether step 1 goes to the re-paste menu (install.md): `done`, `partial` still signed in (PR23b, P3: a plugin
36
+ * off), or `unknown` only because the 2 s account check went unanswered (offline, a slow server): a set-up
37
+ * computer never gets a new sign-in tab for that (D48, fixes-1107 item 2c). A refused key still signs in.
38
+ */
39
+ function isSetUp(setup, env = {}) {
31
40
  if (!setup || typeof setup !== "object") return false;
41
+ const why = Array.isArray(setup.why) ? setup.why : [];
32
42
  if (setup.state === "done") return true;
33
- return setup.state === "partial" && !(Array.isArray(setup.why) && setup.why.includes(SIGNED_OUT_GAP));
43
+ if (setup.state === "unknown") return why.length === 1 && why[0] === UNCHECKED_GAP && isSavedAddress(env);
44
+ return setup.state === "partial" && !why.includes(SIGNED_OUT_GAP);
45
+ }
46
+
47
+ /**
48
+ * Whether this call aims at the saved sign-in's own server (`PROBE_BASE_URL` unset, or the same address): only
49
+ * there does the CLI ask about the key (D26), so elsewhere `credential_unchecked` means "never asked" and the
50
+ * call signs in to that server.
51
+ */
52
+ function isSavedAddress(env) {
53
+ if (!env.PROBE_BASE_URL) return true;
54
+ return toAddress(env.PROBE_BASE_URL) === toAddress(getSignInBase({ ...env, PROBE_BASE_URL: "" }));
55
+ }
56
+
57
+ /** `url` as two addresses compare (the CLI's `normalize_endpoint`): host lower case, default port and trailing
58
+ * slashes dropped. */
59
+ function toAddress(url) {
60
+ try {
61
+ const parsed = new URL(String(url).trim());
62
+ return `${parsed.protocol}//${parsed.host}${parsed.pathname.replace(/\/+$/, "")}`;
63
+ } catch {
64
+ return String(url).trim().replace(/\/+$/, "");
65
+ }
34
66
  }
35
67
 
36
68
  /** The last stdout line as an object, or null. */
@@ -59,11 +91,11 @@ function runSetupCheck({ launcher, deadlineMs, env = process.env }) {
59
91
  if (ran.error || ran.signal) return { check: SetupCheck.TIMED_OUT, stdout: "", code: 1 };
60
92
  const answer = getLastAnswer(ran.stdout);
61
93
  const code = ran.status === null ? 1 : ran.status;
62
- if (answer && isSetUp(answer.setup)) return { check: SetupCheck.SET_UP, stdout: ran.stdout, code };
94
+ if (answer && isSetUp(answer.setup, env)) return { check: SetupCheck.SET_UP, stdout: ran.stdout, code };
63
95
  if (answer && answer.ok === false && typeof answer.reason === "string") {
64
96
  return { check: SetupCheck.REFUSED, stdout: ran.stdout, code };
65
97
  }
66
98
  return { check: SetupCheck.NOT_SET_UP, stdout: ran.stdout, code };
67
99
  }
68
100
 
69
- module.exports = { SIGNED_OUT_GAP, SetupCheck, isSetUp, runSetupCheck };
101
+ module.exports = { SIGNED_OUT_GAP, SetupCheck, UNCHECKED_GAP, isSetUp, runSetupCheck };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "probe-research",
3
- "version": "0.25.0",
3
+ "version": "0.26.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"
@@ -26,6 +26,6 @@
26
26
  "probe-research"
27
27
  ],
28
28
  "scripts": {
29
- "test": "node --test test/resolve.test.js test/sign-in.test.js"
29
+ "test": "node --test test/resolve.test.js test/sign-in.test.js test/contract.test.js test/setup-check.test.js"
30
30
  }
31
31
  }