@voyager-crew/cli 0.3.0 → 0.5.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@voyager-crew/cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Ask ChatGPT from your terminal or your coding agent, through the Voyager browser extension",
5
5
  "keywords": [
6
6
  "chatgpt",
@@ -42,11 +42,12 @@
42
42
  "format": "oxfmt",
43
43
  "format:check": "oxfmt --check",
44
44
  "verify": "bun run format:check && bun run lint:check && bun run typecheck && bun run test",
45
- "prepublishOnly": "bun run verify && bun run build"
45
+ "prepublishOnly": "bun run verify && bun run build",
46
+ "prepare": "node scripts/install-git-hooks.cjs"
46
47
  },
47
48
  "devDependencies": {
48
49
  "@types/node": "^24.9.0",
49
- "@voyager-crew/bridge-protocol": "^0.3.0",
50
+ "@voyager-crew/bridge-protocol": "^0.5.0",
50
51
  "fflate": "0.8.2",
51
52
  "oxfmt": "^0.65.0",
52
53
  "oxlint": "^1.80.0",
@@ -60,15 +60,17 @@ voyager ask --json --project <project> "Use thesis.zip to …" # a new chat in
60
60
 
61
61
  ## Google Drive and GitHub
62
62
 
63
- ChatGPT's own Google Drive and GitHub apps can read files instead of an upload through the page. They act as the person's connected accounts, with no confirmation step, and must already be connected in ChatGPT.
63
+ ChatGPT's own Google Drive and GitHub apps can read files instead of an upload through the page. They act as the person's connected accounts and must already be connected in ChatGPT.
64
64
 
65
65
  ```sh
66
- voyager ask --json --drive ./paper.pdf --drive ./src "Review these" # put on Drive, link in the prompt
66
+ voyager ask --json --drive ./paper.pdf --drive ./src "Review these" # put on Drive, file ids in the prompt
67
67
  voyager ask --json --repo owner/name "Fix the failing test" # owner/name@ref for another ref
68
68
  ```
69
69
 
70
70
  - `--drive` packs like `--attach` (folders zipped, credentials left out) but has no 64 MiB bridge limit (512 MiB per file or zip; files over 20 MiB inside a folder are still left out), and uploads with rclone into a new folder under `$VOYAGER_DRIVE_REMOTE` (or `driveRemote` in `~/.voyager/config.json`), such as `gdrive:Voyager`. Files stay on Drive. Without rclone or a destination it is `bad-request`; the person sets that up. ChatGPT's Drive app must use the same Google account as the rclone remote.
71
71
  - `--repo` asks ChatGPT to commit only to a new `chatgpt/<time>-<id>` branch, printed on stderr; the app could write elsewhere, so check the branch before merging anything. A repository the app cannot reach ends as `permission-missing` (exit 3): the person adds it at github.com/settings/installations. The reply is still saved (`error.details.responsePath`).
72
+ - Before some app actions (writing to Drive, say) ChatGPT stops the reply on an approval card ("Allow ChatGPT to use Google Drive?"). Without `--approve-apps` the job ends as `approval-required` (exit 3); `error.message` holds the conversation link, where the person answers it, then `voyager read <link> --json` gets the reply. Pass `--approve-apps always` (ChatGPT's "Always allow") or `--approve-apps once` only when the person has said to answer it for them; it needs Voyager 2.2.0 or later.
73
+ - No rclone destination, but Google Drive for desktop is installed (a `~/Library/CloudStorage/GoogleDrive-*` folder on macOS): ask the person whether to share the files through it. On a yes, copy them into a new folder under its `My Drive`, wait until Drive has synced them, then name the folder and files in the prompt and ask ChatGPT to read them with its Google Drive app. Write names, not drive.google.com links: Voyager extensions up to 2.1.1 fail to send a prompt holding a Drive link.
72
74
 
73
75
  ## Long replies
74
76
 
@@ -84,19 +86,32 @@ voyager job wait <jobId> --timeout 10m --json
84
86
  - Exit 4 (`"waitTimedOut": true`): the job is still running. Run the same `voyager job wait` again. Never send the prompt again.
85
87
  - Any other exit: `job wait` prints exactly what `voyager ask --json` would have printed, with the same exit codes.
86
88
 
89
+ For work that runs in ChatGPT's sandbox (building, running tests or simulations, rendering or generating files), add `--timebox 70`. A Pro turn doing that can lose its connection after about 80 minutes and then delivers nothing. The flag adds a paragraph asking ChatGPT to wrap up at 70 minutes and hand over what it has: finished and unfinished work apart, in one ZIP, with a first line `finished N / unfinished M / about X minutes`. Questions it only reads and thinks about do not need it.
90
+
91
+ ## Writing the prompt
92
+
93
+ ChatGPT sees nothing of your conversation, so the prompt carries everything. Pro is careful by nature, which shapes how to write for it:
94
+
95
+ - Start with a few lines on what you want: the main task, what is in and out of scope, what to deliver, and the one or two criteria that matter most. The rest of the prompt is material for those lines.
96
+ - Give the purpose, the criteria and the trade-offs, not a list of orders. Pro reads "must" and "never" as hard limits and turns defensive: it reports everything and is slow to deliver.
97
+ - Ask it to judge ("decide whether X holds"), not to confirm ("confirm that X holds").
98
+ - Say what it cannot see: callers outside the material, and the real defaults (timeouts, limits), so it does not rate severity from settings nobody uses.
99
+ - In ordinary debugging or review work, avoid words like bypass, exploit, attack, inject, payload or crack; a safety check can take such a prompt for intrusion work and stop the turn halfway. Say workaround, trigger condition, defect or stress test.
100
+ - When files should come back, ask for one ZIP.
101
+
87
102
  ## Exit codes
88
103
 
89
- | Code | Meaning | Next step |
90
- | ---- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
91
- | 0 | succeeded (also when some `failedFiles` could not be downloaded) | read `responsePath` and `files`; report `failedFiles` |
92
- | 2 | failed (bad input, or the page changed); `send-unverified`: the prompt may be sent | report `error.message`; never resend `send-unverified` |
93
- | 3 | needs a person (`login-required`, `challenge`, `rate-limited`, `policy-denied`, …) | stop and tell the person what `error.code` asks of them |
94
- | 4 | wait timed out; job continues | `voyager job wait <jobId> --json` again; do not resend |
95
- | 5 | busy: another job runs (`error.details.activeJobId`) | wait for that job, or ask the person |
96
- | 6 | lost page or server (`detached`), the reply stalled (`reply-stalled`), or cancelled | tell the person; the prompt may already be in ChatGPT |
97
- | 7 | not paired, or the extension is offline | ask the person to pair or open the browser |
98
-
99
- Exactly one job runs at a time, and jobs are never queued. Each prompt is submitted **once**. After any exit other than 0, report to the person and let them decide; a second `voyager ask` with the same prompt would send it again. `send-unverified` means the page may have sent it, so the person checks ChatGPT first.
104
+ | Code | Meaning | Next step |
105
+ | ---- | -------------------------------------------------------------------------------------- | ------------------------------------------------------- |
106
+ | 0 | succeeded (also when some `failedFiles` could not be downloaded) | read `responsePath` and `files`; report `failedFiles` |
107
+ | 2 | failed (bad input, or the page changed); `send-unverified`: the prompt may be sent | report `error.message`; never resend `send-unverified` |
108
+ | 3 | needs a person (`login-required`, `challenge`, `approval-required`, `rate-limited`, …) | stop and tell the person what `error.code` asks of them |
109
+ | 4 | wait timed out; job continues | `voyager job wait <jobId> --json` again; do not resend |
110
+ | 5 | busy: no room for this job (`error.details.activeJobId`, `maxJobs`, `conflict`) | wait for that job, or ask the person |
111
+ | 6 | lost page or server (`detached`), the reply stalled (`reply-stalled`), or cancelled | tell the person; the prompt may already be in ChatGPT |
112
+ | 7 | not paired, or the extension is offline | ask the person to pair or open the browser |
113
+
114
+ One job runs at a time unless the person turned on parallel jobs in the Voyager popup: then `voyager status --json` shows `maxJobs` above 1, and that many jobs, of this agent or others, run side by side, each in its own tab. Jobs are never queued. Two asks into the same conversation, or two `project` changes, never run together: the later one is `busy` with `error.details.conflict`. Jobs side by side also take turns at typing and clicking: a job held up by another job stuck past the time its step may take ends with exit 5 mid-job (`error.details.pageTurn`), and that step was never sent; if it was approving an app card, the prompt is already in ChatGPT, so do not ask again. With jobs side by side, follow up only with `--chat <the conversationId your ask returned>`; never `--continue`. Each prompt is submitted **once**. After any exit other than 0, report to the person and let them decide; a second `voyager ask` with the same prompt would send it again. `send-unverified` means the page may have sent it, so the person checks ChatGPT first.
100
115
 
101
116
  ## The browser tab
102
117