probe-research 0.23.0 → 0.25.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.
@@ -32,6 +32,7 @@ const os = require("node:os");
32
32
  const path = require("node:path");
33
33
 
34
34
  const agentRun = require("../lib/agent-run");
35
+ const approval = require("../lib/approval-watch");
35
36
  const download = require("../lib/background-download");
36
37
  const setupCheck = require("../lib/setup-check");
37
38
  const signIn = require("../lib/sign-in");
@@ -457,13 +458,13 @@ function getAgentStep(forwarded) {
457
458
  return [AgentStep.STATUS, AgentStep.IMPORT, AgentStep.EXAMPLE].includes(forwarded[0]) ? forwarded[0] : AgentStep.OTHER;
458
459
  }
459
460
 
460
- /** One bounded `agent_install.refused` for `step`, then the refusal itself (`agentRun.refuse`). */
461
- async function refuseAgent(step, reason, message, code) {
461
+ /** One bounded `agent_install.refused` for `step`, then the refusal itself (`agentRun.refuse`), with `facts`. */
462
+ async function refuseAgent(step, reason, message, code, facts = {}) {
462
463
  await sendLauncherEvent(process.env, REFUSED_EVENT, {
463
464
  step, reason, outcome: code === agentRun.EXIT_AGAIN ? "run_again" : "failed",
464
465
  chat_agent: signIn.detectAgent(process.env),
465
466
  });
466
- agentRun.refuse(reason, message, code);
467
+ agentRun.refuse(reason, message, code, facts);
467
468
  }
468
469
 
469
470
  /** The hidden word the launcher re-runs itself with, detached, to send one of these events after it exits. */
@@ -717,6 +718,12 @@ const NONE_SETUP = Object.freeze({
717
718
  });
718
719
  /** Kept back from the budget for the CLI's own work once the download is in. */
719
720
  const WAIT_RESERVE_MS = 20 * 1000;
721
+ /**
722
+ * What an approved sign-in's CLI needs left once a download is in (PR39): its first start through a new
723
+ * service, then the exchange before its own save reserve (12 s) and margin (3 s). With less, it would
724
+ * answer `waiting_for_approval` though the person approved, so the agent runs it again instead.
725
+ */
726
+ const APPROVED_RESERVE_MS = 30 * 1000;
720
727
  /** How often a running download is looked at again. */
721
728
  const DOWNLOAD_POLL_MS = 1000;
722
729
  /** The uninstall barrier (`probe.shared.updates.uninstall_barrier.path`). */
@@ -808,13 +815,23 @@ function startBackgroundDownload() {
808
815
  return download.startDownload({ launcher: __filename, args: [] });
809
816
  }
810
817
 
811
- /** The detached download itself: the newest CLI, installed for good by its own bootstrap. */
818
+ /**
819
+ * The detached download itself: the newest CLI, installed for good by its own bootstrap. Two steps, so
820
+ * `sign-in --wait` can say which runs (PR39): uv fetches Python and the CLI into its env (running only
821
+ * Python there, no service), then the same env starts the CLI's first service. The first may fail on its
822
+ * own (an old uv that runs no `python` from a tool env): the second downloads too.
823
+ */
812
824
  async function runBackgroundDownload() {
813
825
  const { pinned, spec, missingBuild } = await getLatestSpec();
814
826
  const refresh = getRefreshFlags({ repair: false, missingBuild, pinned });
815
827
  const uv = getUv();
816
- process.exit(download.runDownload([[uv, "tool", "run", "--python", PYTHON_REQUEST, ...refresh, "--from", spec,
817
- "probe", "service", "start", "--min-version", pinned || AGENT_MIN_CLI, "--json"]]));
828
+ process.exit(download.runDownload([
829
+ { stage: download.DownloadStage.DOWNLOADING, isOptional: true,
830
+ command: [uv, "tool", "run", "--python", PYTHON_REQUEST, ...refresh, "--from", spec, "python", "-c", ""] },
831
+ { stage: download.DownloadStage.STARTING,
832
+ command: [uv, "tool", "run", "--python", PYTHON_REQUEST, ...refresh, "--from", spec, "probe", "service",
833
+ "start", "--min-version", pinned || AGENT_MIN_CLI, "--json"] },
834
+ ]));
818
835
  }
819
836
 
820
837
  /** An uninstall stopped halfway is finished (`probe repair`) before the tab opens (D47). */
@@ -832,20 +849,61 @@ async function finishStoppedUninstall(deadlineMs) {
832
849
  }
833
850
  }
834
851
 
835
- /** An agent's call (`step`) while the first download runs: wait within the budget, else `downloading` (75). */
836
- async function waitForRunningDownload(startedMs, step) {
852
+ /** An agent's call (`step`) while the first download runs: wait within the budget, else `downloading` (75).
853
+ * `watch` (`sign-in --wait`'s approval, PR39) is read meanwhile and told each stage the download runs. */
854
+ async function waitForRunningDownload(startedMs, step, watch = null) {
837
855
  const until = startedMs + agentRun.AGENT_BUDGET_MS - WAIT_RESERVE_MS;
838
856
  for (;;) {
839
857
  const record = download.loadDownload();
840
- if (!record || record.state !== download.DownloadState.RUNNING) return record;
841
- if (Date.now() >= until) {
842
- await refuseAgent(step, agentRun.Reason.DOWNLOADING, "Probe is still downloading: run the same command again.",
843
- agentRun.EXIT_AGAIN);
844
- }
858
+ const isRunning = record && record.state === download.DownloadState.RUNNING;
859
+ await updateWatch(watch, step, isRunning ? record.stage || download.DownloadStage.DOWNLOADING : null);
860
+ if (!isRunning) return record;
861
+ if (Date.now() >= until) await refuseUnfinished(step, watch, record.stage || download.DownloadStage.DOWNLOADING);
845
862
  await sleep(DOWNLOAD_POLL_MS);
846
863
  }
847
864
  }
848
865
 
866
+ /**
867
+ * Read `watch` and report `stage` (none without a watch). The approval read while Probe still installs is
868
+ * answered at once (PR39b): `downloading` with `approved`, who and the stage's `say`, so the agent says it
869
+ * within seconds and runs the wait again for the install. A denied or expired sign-in stops here (PR39).
870
+ */
871
+ async function updateWatch(watch, step, stage) {
872
+ if (!watch) return;
873
+ if (await watch.update(stage)) {
874
+ await refuseAgent(step, agentRun.Reason.DOWNLOADING, "Probe is still installing: run the same command again.",
875
+ agentRun.EXIT_AGAIN, watch.getRunAgainFacts(stage));
876
+ }
877
+ const again = "run `npx -y probe-research sign-in --json` for a new one.";
878
+ if (watch.status === signIn.ApprovalStatus.DENIED) {
879
+ signIn.clearPending();
880
+ await refuseAgent(step, agentRun.Reason.INCOMPLETE, `The sign-in was denied in the browser: ${again}`, 1);
881
+ }
882
+ if (watch.status === signIn.ApprovalStatus.EXPIRED) {
883
+ signIn.clearPending();
884
+ await refuseAgent(step, agentRun.Reason.SIGN_IN_EXPIRED, `The sign-in link expired: ${again}`, 1);
885
+ }
886
+ }
887
+
888
+ /**
889
+ * Out of time while Probe installs (75): what is true now (PR39). Approved: `downloading` with
890
+ * `approved`, who and the stage's `say`, never "waiting for approval". Not approved yet: waiting for it.
891
+ * Unknown (no watch, an older server): `message`.
892
+ */
893
+ async function refuseUnfinished(step, watch, stage, message = "Probe is still downloading: run the same command again.") {
894
+ if (watch && watch.isApproved()) {
895
+ watch.markSaid(stage);
896
+ await refuseAgent(step, agentRun.Reason.DOWNLOADING, "Probe is still installing: run the same command again.",
897
+ agentRun.EXIT_AGAIN, watch.getRunAgainFacts(stage));
898
+ }
899
+ if (watch && watch.isPending()) {
900
+ await refuseAgent(step, agentRun.Reason.WAITING_FOR_APPROVAL,
901
+ "Waiting for the browser approval while Probe installs: run this again.", agentRun.EXIT_AGAIN,
902
+ watch.getRunAgainFacts(stage));
903
+ }
904
+ await refuseAgent(step, agentRun.Reason.DOWNLOADING, message, agentRun.EXIT_AGAIN);
905
+ }
906
+
849
907
  /** `sign-in`: the tab within seconds, the download behind it; `sign-in --wait`: the CLI finishes it. */
850
908
  async function runSignIn(rest, startedMs) {
851
909
  const deadlineMs = startedMs + agentRun.AGENT_BUDGET_MS;
@@ -892,19 +950,26 @@ async function answerIfSetUp(deadlineMs) {
892
950
  process.exit(ran.code);
893
951
  }
894
952
 
895
- /** The downloaded `probe`, asked again while the budget lasts when the download finished (`done`). */
896
- async function findDownloadedProbe(done, startedMs) {
953
+ /** The downloaded `probe`, asked again while the budget lasts when the download finished (`done`); its
954
+ * first service restarts meanwhile, which `watch` reports as still starting (PR39). */
955
+ async function findDownloadedProbe(done, startedMs, step, watch = null) {
897
956
  const until = startedMs + agentRun.AGENT_BUDGET_MS - WAIT_RESERVE_MS;
898
957
  for (;;) {
899
958
  const probe = findProbe(AGENT_MIN_CLI);
900
959
  if (probe || !done || done.state !== download.DownloadState.DONE || Date.now() >= until) return probe;
960
+ await updateWatch(watch, step, approval.InstallStage.STARTING);
901
961
  await sleep(DOWNLOAD_POLL_MS);
902
962
  }
903
963
  }
904
964
 
905
- /** `sign-in --wait`: the download first (within the budget), then the CLI polls for the approval. */
965
+ /**
966
+ * `sign-in --wait`: the CLI polls for the approval and saves it. With no `probe` yet, the download first
967
+ * (within the budget), while the approval is read from the server (PR39): the call that reads it answers at
968
+ * once (PR39b); the next one waits for the install and says each stage as it happens.
969
+ */
906
970
  async function waitForSignIn(json, startedMs) {
907
- if (!signIn.loadPending()) {
971
+ const pending = signIn.loadPending();
972
+ if (!pending) {
908
973
  await refuseAgent(AgentStep.SIGN_IN_WAIT, agentRun.Reason.SIGN_IN_EXPIRED,
909
974
  "No sign-in is waiting (or it expired): run `npx -y probe-research sign-in --json` for a new one.", 1);
910
975
  }
@@ -913,29 +978,44 @@ async function waitForSignIn(json, startedMs) {
913
978
  "An uninstall of Probe stopped halfway: run `npx -y probe-research sign-in --json` again to finish it.",
914
979
  agentRun.EXIT_AGAIN);
915
980
  }
916
- const probe = await getAgentProbe(startedMs, AgentStep.SIGN_IN_WAIT);
981
+ const watch = new approval.ApprovalWatch(pending);
982
+ const probe = await getAgentProbe(startedMs, AgentStep.SIGN_IN_WAIT, watch);
983
+ // Read only while it waited for the install: a `probe` already here is handed the sign-in at once.
984
+ if (watch.hasWatched()) await sayInstalled(watch, startedMs);
917
985
  return runAgentCall(probe, ["wizard", "--action", "login", "--pending", ...(json ? ["--json"] : [])], startedMs,
918
986
  AgentStep.SIGN_IN_WAIT);
919
987
  }
920
988
 
989
+ /** Probe installed during the wait (PR39): approved, say so, and hand the CLI the save only with time for it. */
990
+ async function sayInstalled(watch, startedMs) {
991
+ await updateWatch(watch, AgentStep.SIGN_IN_WAIT, approval.InstallStage.DONE);
992
+ if (!watch.isApproved() || startedMs + agentRun.AGENT_BUDGET_MS - Date.now() >= APPROVED_RESERVE_MS) return;
993
+ watch.markSaid(approval.InstallStage.DONE);
994
+ await refuseAgent(AgentStep.SIGN_IN_WAIT, agentRun.Reason.RUN_AGAIN,
995
+ "Probe is installed, with too little time left to save the sign-in: run the same command again.",
996
+ agentRun.EXIT_AGAIN, watch.getRunAgainFacts(approval.InstallStage.DONE));
997
+ }
998
+
921
999
  /** A `probe` at the agent floor: the one here, else the first download's (started if none runs), waited
922
1000
  * for within the budget; else `downloading` (75, run it again), the service's reason when the download
923
- * ended on one (`no_service`, `service_lost`, `updating`), or `incomplete` with the download's log. */
924
- async function getAgentProbe(startedMs, step) {
1001
+ * ended on one (`no_service`, `service_lost`, `updating`), or `incomplete` with the download's log.
1002
+ * `watch`: `sign-in --wait`'s approval, read meanwhile (PR39); its facts ride every refusal. */
1003
+ async function getAgentProbe(startedMs, step, watch = null) {
925
1004
  const found = findProbe(AGENT_MIN_CLI);
926
1005
  if (found) return found;
927
1006
  const record = download.loadDownload();
928
1007
  // A finished download whose `probe` is gone (removed since) is downloaded again, never waited on.
929
1008
  const isGone = record && record.state === download.DownloadState.DONE && getProbeCommands().length === 0;
930
1009
  if (!record || record.state === download.DownloadState.FAILED || isGone) startBackgroundDownload();
931
- const done = await waitForRunningDownload(startedMs, step);
932
- const probe = await findDownloadedProbe(done, startedMs);
1010
+ const done = await waitForRunningDownload(startedMs, step, watch);
1011
+ const probe = await findDownloadedProbe(done, startedMs, step, watch);
933
1012
  if (!probe && done && done.state === download.DownloadState.DONE) {
934
1013
  // Installed, but its `probe` did not answer yet: the Probe service it just started restarts
935
1014
  // once for its first update, and `probe --version` goes through it (PR3b dry run, 1 in 4).
936
- await refuseAgent(step, agentRun.Reason.DOWNLOADING, "Probe is finishing its install: run the same command again.",
937
- agentRun.EXIT_AGAIN);
1015
+ await refuseUnfinished(step, watch, approval.InstallStage.STARTING,
1016
+ "Probe is finishing its install: run the same command again.");
938
1017
  }
1018
+ const facts = watch ? watch.getFacts() : {};
939
1019
  const serviceExit = !probe && done && done.state === download.DownloadState.FAILED
940
1020
  ? download.getServiceExit(done.reason) : null;
941
1021
  if (serviceExit !== null) {
@@ -944,12 +1024,12 @@ async function getAgentProbe(startedMs, step) {
944
1024
  await refuseAgent(step, done.reason, serviceExit === agentRun.EXIT_AGAIN
945
1025
  ? `Probe is finishing an update (${done.error}): run the same command again.`
946
1026
  : `Probe downloaded, but its service did not answer, so its install did not finish (${done.error}); ` +
947
- `its log: ${download.getFile(download.LOG_NAME)}`, serviceExit);
1027
+ `its log: ${download.getFile(download.LOG_NAME)}`, serviceExit, facts);
948
1028
  }
949
1029
  if (!probe) {
950
1030
  await refuseAgent(step, agentRun.Reason.INCOMPLETE,
951
1031
  `Probe did not download (${(done && done.error) || "no probe command after it"}); ` +
952
- `its log: ${download.getFile(download.LOG_NAME)}`, 1);
1032
+ `its log: ${download.getFile(download.LOG_NAME)}`, 1, facts);
953
1033
  }
954
1034
  return probe;
955
1035
  }
package/lib/agent-run.js CHANGED
@@ -14,6 +14,8 @@ const { spawn } = require("node:child_process");
14
14
 
15
15
  /** The whole command's time, the download wait included. */
16
16
  const AGENT_BUDGET_MS = 110 * 1000;
17
+ /** Test-only: a shorter budget in seconds (never a longer one), so the run-again answers test in seconds. */
18
+ const TEST_BUDGET_ENV = "PROBE_LAUNCHER_TEST_BUDGET_S";
17
19
  /** After SIGTERM, this long before SIGKILL. */
18
20
  const KILL_GRACE_MS = 5 * 1000;
19
21
  /** The variable the CLI reads its deadline from (epoch seconds; `agent_install.budget.DEADLINE_ENV`). */
@@ -96,8 +98,14 @@ function runWithBackstop(cmd, args, { deadlineMs, env = process.env } = {}) {
96
98
  });
97
99
  }
98
100
 
101
+ /** The budget this run has: AGENT_BUDGET_MS, or a shorter test one (TEST_BUDGET_ENV). */
102
+ function getBudgetMs(env) {
103
+ const seconds = Number(env[TEST_BUDGET_ENV]);
104
+ return seconds > 0 && seconds * 1000 < AGENT_BUDGET_MS ? seconds * 1000 : AGENT_BUDGET_MS;
105
+ }
106
+
99
107
  module.exports = {
100
- AGENT_BUDGET_MS,
108
+ AGENT_BUDGET_MS: getBudgetMs(process.env),
101
109
  CLI_MARGIN_MS,
102
110
  DEADLINE_ENV,
103
111
  EXIT_AGAIN,
@@ -0,0 +1,150 @@
1
+ /**
2
+ * `sign-in --wait` while Probe installs (PR39): the approval read from the server at once and every few
3
+ * seconds. The call that reads it while Probe still installs answers at once (PR39b), so the agent says
4
+ * "You're approved" within seconds; the approval is kept (`approval.json`), so the next call only waits for
5
+ * the install, one JSON line per stage as it happens. Richard's fresh Mac approved at once and heard
6
+ * "waiting for approval" for minutes: the old wait read the approval only through the CLI, after the download.
7
+ */
8
+
9
+ const fs = require("node:fs");
10
+ const path = require("node:path");
11
+
12
+ const { writeLine } = require("./agent-run");
13
+ const { DownloadStage } = require("./background-download");
14
+ const { ApprovalStatus, fetchApproval, getStateFolder } = require("./sign-in");
15
+
16
+ /** Where Probe's install on this computer is: the download's stages, then done (its `probe` answers). */
17
+ const InstallStage = Object.freeze({ ...DownloadStage, DONE: "done" });
18
+ /** Each stage as the person reads it (Richard's words, 2026-11-07). */
19
+ const STAGE_WORDS = Object.freeze({
20
+ [InstallStage.DOWNLOADING]: "Probe is still installing on this computer: downloading.",
21
+ [InstallStage.STARTING]: "Probe is still installing on this computer: starting its service for the first time.",
22
+ [InstallStage.DONE]: "Probe is installed on this computer: done.",
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
+ /** The shortest gap between two reads; the server's poll interval when longer. */
27
+ const MIN_READ_GAP_MS = 2000;
28
+ /** This attempt's approval and the last stage said, kept for its next `sign-in --wait` (0600, no secret). */
29
+ const APPROVAL_NAME = "approval.json";
30
+ const APPROVAL_VERSION = 1;
31
+ /** Answers that never change: not asked again. */
32
+ const SETTLED = Object.freeze([ApprovalStatus.APPROVED, ApprovalStatus.DENIED, ApprovalStatus.EXPIRED,
33
+ ApprovalStatus.ONBOARDING_REQUIRED, ApprovalStatus.UNREADABLE]);
34
+
35
+ /** The line the agent shows once the person approved: who, and where the install is. */
36
+ function getApprovedSay(account, stage) {
37
+ return `You're approved${account ? ` (${account})` : ""}. ${STAGE_WORDS[stage]}`;
38
+ }
39
+
40
+ /** The line the agent shows while the approval has not come: the tab to approve in. */
41
+ function getWaitingSay(pending) {
42
+ const link = pending.verification_uri_complete ? `: ${pending.verification_uri_complete}` : "";
43
+ return `Waiting for your approval in the browser${link}${pending.user_code ? ` (code ${pending.user_code})` : ""}.`;
44
+ }
45
+
46
+ /** The approval an earlier call of this attempt read, or null. */
47
+ function loadApproval(attempt) {
48
+ try {
49
+ const data = JSON.parse(fs.readFileSync(path.join(getStateFolder(), APPROVAL_NAME), "utf8"));
50
+ return data && data.v === APPROVAL_VERSION && attempt && data.attempt === attempt ? data : null;
51
+ } catch {
52
+ return null;
53
+ }
54
+ }
55
+
56
+ /** Keep this attempt's approval and the stage last said: whether it was kept. */
57
+ function saveApproval(attempt, account, stage) {
58
+ if (!attempt) return false;
59
+ try {
60
+ fs.mkdirSync(getStateFolder(), { recursive: true, mode: 0o700 });
61
+ const file = path.join(getStateFolder(), APPROVAL_NAME);
62
+ const temp = `${file}.${process.pid}`;
63
+ fs.writeFileSync(temp, JSON.stringify({ v: APPROVAL_VERSION, attempt, account, stage }), { mode: 0o600 });
64
+ fs.renameSync(temp, file);
65
+ return true;
66
+ } catch {
67
+ return false;
68
+ }
69
+ }
70
+
71
+ class ApprovalWatch {
72
+ /** `pending`: the sign-in `startSignIn` left. `write` takes each progress line (stdout by default). An
73
+ * approval an earlier call of this attempt read is known at once, never read again. */
74
+ constructor(pending, { fetchImpl = fetch, write = writeLine, now = Date.now } = {}) {
75
+ this.pending = pending;
76
+ this.fetchImpl = fetchImpl;
77
+ this.write = write;
78
+ this.now = now;
79
+ const kept = loadApproval(pending.attempt);
80
+ this.status = kept ? ApprovalStatus.APPROVED : null;
81
+ this.account = kept && typeof kept.account === "string" ? kept.account : null;
82
+ this.reportedStage = kept ? kept.stage || null : null;
83
+ this.readGapMs = Math.max(MIN_READ_GAP_MS, (Number(pending.interval) || 0) * 1000);
84
+ this.nextReadMs = 0;
85
+ this.isWatching = false;
86
+ }
87
+
88
+ /**
89
+ * Read the approval when a read is due. True when it came in this read while Probe still installs
90
+ * (`stage` set, not done): the caller answers at once with `getRunAgainFacts(stage)`, which this
91
+ * reports as said. Otherwise, once approved, one line for `stage` (InstallStage) if it is new.
92
+ */
93
+ async update(stage = null) {
94
+ this.isWatching = true;
95
+ let isNew = false;
96
+ if (!SETTLED.includes(this.status) && this.now() >= this.nextReadMs) {
97
+ this.nextReadMs = this.now() + this.readGapMs;
98
+ const read = await fetchApproval(this.pending, { fetchImpl: this.fetchImpl });
99
+ if (read) {
100
+ isNew = read.status === ApprovalStatus.APPROVED;
101
+ ({ status: this.status, account: this.account } = read);
102
+ }
103
+ }
104
+ // Ends the call only when the next one will know: unkept, every call would read it anew and end again.
105
+ if (isNew && stage && stage !== InstallStage.DONE && saveApproval(this.pending.attempt, this.account, stage)) {
106
+ this.reportedStage = stage;
107
+ return true;
108
+ }
109
+ if (this.isApproved() && stage && stage !== this.reportedStage) {
110
+ this.markSaid(stage);
111
+ this.write(JSON.stringify({ event: PROGRESS_EVENT, say: getApprovedSay(this.account, stage), approved: true,
112
+ account: this.account, stage }));
113
+ }
114
+ if (isNew) saveApproval(this.pending.attempt, this.account, this.reportedStage);
115
+ return false;
116
+ }
117
+
118
+ /** `stage` was said to the person (a line or an answer): kept for this attempt's next call; whether it was. */
119
+ markSaid(stage) {
120
+ this.reportedStage = stage;
121
+ return saveApproval(this.pending.attempt, this.account, stage);
122
+ }
123
+
124
+ /** Whether this call watched the install (it does only while Probe installs). */
125
+ hasWatched() {
126
+ return this.isWatching;
127
+ }
128
+
129
+ isApproved() {
130
+ return this.status === ApprovalStatus.APPROVED;
131
+ }
132
+
133
+ isPending() {
134
+ return this.status === ApprovalStatus.PENDING;
135
+ }
136
+
137
+ /** What any answer adds once the approval is known: `approved`, and who approved. */
138
+ getFacts() {
139
+ if (this.isApproved()) return { approved: true, account: this.account };
140
+ return this.isPending() ? { approved: false } : {};
141
+ }
142
+
143
+ /** What a run-again answer adds: the facts and the line to show, approved at `stage` or still waiting. */
144
+ getRunAgainFacts(stage) {
145
+ if (this.isApproved()) return { say: getApprovedSay(this.account, stage), ...this.getFacts(), stage };
146
+ return this.isPending() ? { say: getWaitingSay(this.pending), ...this.getFacts() } : {};
147
+ }
148
+ }
149
+
150
+ module.exports = { APPROVAL_NAME, ApprovalWatch, InstallStage, PROGRESS_EVENT, getApprovedSay };
@@ -27,6 +27,9 @@ const DOWNLOAD_CAP_MS = 10 * 60 * 1000;
27
27
  const DOWNLOAD_VERB = "--probe-background-download";
28
28
 
29
29
  const DownloadState = Object.freeze({ RUNNING: "running", DONE: "done", FAILED: "failed" });
30
+ /** A running download's step (`stage` on its record, PR39): uv fetching Python and the CLI, then the CLI's
31
+ * first Probe service starting. `sign-in --wait` tells the person which, once they approved. */
32
+ const DownloadStage = Object.freeze({ DOWNLOADING: "downloading", STARTING: "starting" });
30
33
  /**
31
34
  * A step's exit that is the Probe service's answer, not the download's (PR29): the `probe` shim's own
32
35
  * (`ShimReason.BY_EXIT`: no service answered, it went away mid-command, an update held it) and
@@ -137,8 +140,9 @@ function startDownload({ launcher, args, env = process.env }) {
137
140
  }
138
141
 
139
142
  /**
140
- * The detached process's work: each step (`[cmd, ...args]`) in turn within DOWNLOAD_CAP_MS, its
141
- * output in the log, its end in the record. Returns the exit status.
143
+ * The detached process's work: each step (`{stage, command: [cmd, ...args], isOptional}`) in turn within
144
+ * DOWNLOAD_CAP_MS, its stage on the record while it runs, its output in the log, its end in the record.
145
+ * An optional step that fails is passed over (the next one does its work too). Returns the exit status.
142
146
  */
143
147
  function runDownload(steps) {
144
148
  if (!takeLock()) {
@@ -150,13 +154,15 @@ function runDownload(steps) {
150
154
  const started = Date.now();
151
155
  saveDownload({ state: DownloadState.RUNNING, pid: process.pid, started_at: started / 1000 });
152
156
  try {
153
- for (const step of steps) {
154
- let { ran, logged } = runStep(step, started);
157
+ for (const { stage, command, isOptional = false } of steps) {
158
+ saveDownload({ state: DownloadState.RUNNING, stage, pid: process.pid, started_at: started / 1000 });
159
+ let { ran, logged } = runStep(command, started);
160
+ if (isOptional) continue;
155
161
  // Once more with a fresh deadline when its service never answered: uv's own download may have used up
156
162
  // the first one before `probe` started, and uv's copy is ready by now (PR29).
157
- if (ran && !ran.error && RETRIED_EXITS.includes(ran.status)) ({ ran, logged } = runStep(step, started));
163
+ if (ran && !ran.error && RETRIED_EXITS.includes(ran.status)) ({ ran, logged } = runStep(command, started));
158
164
  if (!ran || ran.error || ran.status !== 0) {
159
- saveDownload({ state: DownloadState.FAILED, pid: process.pid, ...getFailure(step[0], ran, logged),
165
+ saveDownload({ state: DownloadState.FAILED, pid: process.pid, ...getFailure(command[0], ran, logged),
160
166
  finished_at: Date.now() / 1000 });
161
167
  return 1;
162
168
  }
@@ -235,6 +241,7 @@ function loadStepMessage(offset) {
235
241
  module.exports = {
236
242
  DOWNLOAD_CAP_MS,
237
243
  DOWNLOAD_VERB,
244
+ DownloadStage,
238
245
  DownloadState,
239
246
  LOG_NAME,
240
247
  SERVICE_EXITS,
package/lib/sign-in.js CHANGED
@@ -21,6 +21,20 @@ const STATE_FOLDER = [".local", "state", "probe", "agent-install"];
21
21
  const PENDING_NAME = "sign-in.json";
22
22
  const PENDING_VERSION = 1;
23
23
  const START_PATH = "/auth/device/code";
24
+ /** Where the waiting sign-in stands, read without exchanging it (PR39). */
25
+ const STATUS_PATH = "/auth/device/status";
26
+ /** The server's answers (`DeviceAuthorizationStatusOut.status`), and UNREADABLE: this server cannot say
27
+ * (an older one, no such route) or never will for this request, so it is not asked again. */
28
+ const ApprovalStatus = Object.freeze({
29
+ PENDING: "pending",
30
+ APPROVED: "approved",
31
+ DENIED: "denied",
32
+ EXPIRED: "expired",
33
+ ONBOARDING_REQUIRED: "onboarding_required",
34
+ UNREADABLE: "unreadable",
35
+ });
36
+ /** How long one approval read may take: the wait goes on without it. */
37
+ const APPROVAL_TIMEOUT_MS = 3000;
24
38
  /** The request, as the CLI's `AGENT_CLIENT_CONTEXT` / `AGENT_GRANTS` spell it. */
25
39
  const AGENT_CLIENT_CONTEXT = Object.freeze({ install: true, surface: "agent" });
26
40
  const AGENT_GRANTS = Object.freeze(["api", "mcp"]);
@@ -235,17 +249,54 @@ function loadPending(now = Date.now() / 1000) {
235
249
  }
236
250
  }
237
251
 
252
+ /** The request `startSignIn` left, removed: a denied or expired one is good for nothing (as the CLI clears it). */
253
+ function clearPending() {
254
+ try {
255
+ fs.unlinkSync(path.join(getStateFolder(), PENDING_NAME));
256
+ } catch {}
257
+ }
258
+
259
+ /**
260
+ * Where `pending` stands (`POST /auth/device/status`, PR39): `{status, account}` (`ApprovalStatus`; `account`
261
+ * is the approver's email), or null when it could not be asked this time (offline, slow, a 5xx). It exchanges
262
+ * nothing, so the CLI still mints and saves the keys; the secret goes only to the server it came from.
263
+ */
264
+ async function fetchApproval(pending, { fetchImpl = fetch, timeoutMs = APPROVAL_TIMEOUT_MS } = {}) {
265
+ const unreadable = { status: ApprovalStatus.UNREADABLE, account: null };
266
+ const { base_url: base, device_code: deviceCode, code_verifier: verifier } = pending || {};
267
+ if (![base, deviceCode, verifier].every((value) => typeof value === "string" && value)) return unreadable;
268
+ try {
269
+ const response = await fetchImpl(`${base}${STATUS_PATH}`, {
270
+ method: "POST",
271
+ headers: { "content-type": "application/json", accept: "application/json" },
272
+ body: JSON.stringify({ device_code: deviceCode, code_verifier: verifier }),
273
+ signal: AbortSignal.timeout(timeoutMs),
274
+ });
275
+ if (response.status === 429 || response.status >= 500) return null;
276
+ const data = response.ok ? await response.json().catch(() => null) : null;
277
+ const status = data && data.status;
278
+ if (status === ApprovalStatus.UNREADABLE || !Object.values(ApprovalStatus).includes(status)) return unreadable;
279
+ return { status, account: typeof data.account === "string" && data.account ? data.account : null };
280
+ } catch {
281
+ return null;
282
+ }
283
+ }
284
+
238
285
  module.exports = {
239
286
  AGENT_CLIENT_CONTEXT,
240
287
  AGENT_MARKERS,
241
288
  AGENT_GRANTS,
289
+ ApprovalStatus,
242
290
  PENDING_NAME,
243
291
  STATE_FOLDER,
244
292
  START_PATH,
293
+ STATUS_PATH,
245
294
  TOKEN_NAME_PREFIX,
246
295
  HOSTED_AGENTS,
247
296
  buildRequestBody,
297
+ clearPending,
248
298
  detectAgent,
299
+ fetchApproval,
249
300
  findHostedAgent,
250
301
  getSayLine,
251
302
  getSignInBase,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "probe-research",
3
- "version": "0.23.0",
3
+ "version": "0.25.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"