@voyager-crew/cli 0.3.0 → 0.4.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/README.md CHANGED
@@ -29,7 +29,8 @@ and ChatGPT sees an ordinary chat from your own browser.
29
29
  npm install -g @voyager-crew/cli
30
30
  ```
31
31
 
32
- 2. Install the Voyager extension, version 2.1.0 or later:
32
+ 2. Install the Voyager extension, version 2.1.0 or later (2.2.0 for `--approve-apps` and for saving the
33
+ files a reply offers):
33
34
  [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
34
35
  [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
35
36
  [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/). In its popup, open
@@ -73,6 +74,10 @@ voyager ask --no-wait "…" # prints a job id
73
74
  voyager job wait <id> --timeout 10m # exit 4 means still running: wait again, never resend
74
75
  ```
75
76
 
77
+ A Pro turn that builds, runs or renders things in ChatGPT's sandbox can lose its connection
78
+ after about 80 minutes, and then delivers nothing. `--timebox 70` asks it to wrap up at 70
79
+ minutes and hand over what it has, finished and unfinished work apart, in one ZIP.
80
+
76
81
  ## Projects
77
82
 
78
83
  A ChatGPT project keeps files that every chat in it can read, so a codebase or a paper goes
@@ -104,6 +109,11 @@ a restriction: the app writes wherever its GitHub installation allows, without a
104
109
  repository, voyager stops with exit code 3; add the repository at
105
110
  [github.com/settings/installations](https://github.com/settings/installations).
106
111
 
112
+ Before some app actions, such as writing a file to Drive, ChatGPT stops the reply on a card that asks
113
+ "Allow ChatGPT to use Google Drive?". voyager then stops with exit code 3 and the conversation link, where
114
+ you answer it. With Voyager 2.2.0 or later, pass `--approve-apps always` to have the extension click "Always allow" for you, or
115
+ `--approve-apps once` for "Allow once". The card can come back after "Always allow".
116
+
107
117
  ## Using it from an agent
108
118
 
109
119
  Claude Code, Codex and any other agent that can run shell commands can use Voyager CLI. Install
package/README_ZH.md CHANGED
@@ -26,7 +26,7 @@ Voyager CLI 是 [Voyager](https://github.com/voyager-crew/voyager) 浏览器插
26
26
  npm install -g @voyager-crew/cli
27
27
  ```
28
28
 
29
- 2. 安装 Voyager 插件,需要 2.1.0 或更高版本:
29
+ 2. 安装 Voyager 插件,需要 2.1.0 或更高版本(`--approve-apps` 和保存回复里的文件需要 2.2.0):
30
30
  [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
31
31
  [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
32
32
  [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/)。打开插件弹窗,进入
@@ -65,6 +65,8 @@ voyager ask --no-wait "…" # 输出一个任务 id
65
65
  voyager job wait <id> --timeout 10m # 退出码 4 表示还在跑:接着等,千万别重发问题
66
66
  ```
67
67
 
68
+ Pro 在 ChatGPT 沙箱里做构建、运行、渲染这类重活时,大约 80 分钟后连接可能会断,断了就什么都不交。`--timebox 70` 让它到 70 分钟就收尾,把手上的东西交出来:成品和半成品分开,打成一个 ZIP。
69
+
68
70
  ## 项目
69
71
 
70
72
  ChatGPT 的项目可以存放文件,项目里的每个对话都能读到。代码库或论文传一次就行,不用每次提问都附上。
@@ -94,6 +96,10 @@ voyager ask --repo owner/name "CI 为什么挂了?" # 让 ChatGPT 的 Gi
94
96
  安装能写到哪里,它就能写到哪里,而且不会先问你。读不到仓库时,voyager 以退出码 3 停下,去
95
97
  [github.com/settings/installations](https://github.com/settings/installations) 把仓库加上就行。
96
98
 
99
+ 做某些操作之前(比如往 Drive 写文件),ChatGPT 会在回答里停下,弹一张卡问「允许 ChatGPT 使用 Google Drive 吗?」。
100
+ 这时 voyager 以退出码 3 停下,并给出对话链接,你去那里点。插件 2.2.0 及以上,加 `--approve-apps always` 就由插件替你点「始终允许」,
101
+ `--approve-apps once` 点「允许一次」。点过「始终允许」,这张卡之后也可能再出现。
102
+
97
103
  ## 给 agent 用
98
104
 
99
105
  Claude Code、Codex 以及任何能运行终端命令的 agent 都能用 Voyager CLI。先装上教它们怎么用的 skill:
package/dist/cli.mjs CHANGED
@@ -225,6 +225,7 @@ var ERROR_CATEGORIES = {
225
225
  "model-not-found": "user-action",
226
226
  "effort-unavailable": "user-action",
227
227
  "composer-busy": "user-action",
228
+ "approval-required": "user-action",
228
229
  "tab-hidden": "user-action",
229
230
  "busy-stale": "user-action",
230
231
  "extension-offline": "user-action",
@@ -350,6 +351,7 @@ var OP_NAMES = [
350
351
  "composer.attach",
351
352
  "composer.send",
352
353
  "turns.waitReply",
354
+ "turns.approve",
353
355
  "turns.read",
354
356
  "files.download",
355
357
  "catalog.refresh",
@@ -366,6 +368,7 @@ var MAX_ATTACHMENTS = 10;
366
368
  var MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
367
369
  var WAIT_REPLY_MAX_TIMEOUT_MS = 12 * 60 * 60000;
368
370
  var WAIT_REPLY_DEFAULT_STALL_MS = 20 * 60000;
371
+ var MAX_FILE_CANDIDATES = 100;
369
372
  var CATALOG_HOST_PATTERN = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
370
373
  // node_modules/@voyager-crew/bridge-protocol/src/version.ts
371
374
  var PROTOCOL = { min: 1, max: 1 };
@@ -379,6 +382,7 @@ var OP_VERSIONS = {
379
382
  "composer.attach": 1,
380
383
  "composer.send": 1,
381
384
  "turns.waitReply": 1,
385
+ "turns.approve": 1,
382
386
  "turns.read": 1,
383
387
  "files.download": 1,
384
388
  "catalog.refresh": 1,
@@ -554,11 +558,11 @@ var PROJECT_RESULT_READERS = {
554
558
  // node_modules/@voyager-crew/bridge-protocol/src/validate/ops.ts
555
559
  var CHAT_MODES = ["chat", "work", "unknown"];
556
560
  var SWITCHABLE_MODES2 = ["chat", "work"];
561
+ var APPROVAL_CHOICES = ["always", "once"];
557
562
  var HTTPS_URL2 = { pattern: /^https:\/\//, maxLength: 4096 };
558
563
  var TURN_KEY = { maxLength: 256 };
559
564
  var LABEL = { maxLength: 200, allowEmpty: true };
560
565
  var FILE_NAME2 = { pattern: /^[^/\\\0]+$/, maxLength: 255 };
561
- var MAX_FILE_CANDIDATES = 100;
562
566
  var CATALOG_HOST = { pattern: CATALOG_HOST_PATTERN, maxLength: 253 };
563
567
  var CATALOG_STATUSES = [
564
568
  "updated",
@@ -725,12 +729,22 @@ var PARAM_READERS = {
725
729
  max: WAIT_REPLY_MAX_TIMEOUT_MS
726
730
  });
727
731
  const stableMs = optionalInt(rec, "stableMs", path, issues, { max: 60000 });
732
+ const stopOnApproval = optionalBoolean(rec, "stopOnApproval", path, issues);
728
733
  return {
729
734
  conversationId: readConversationId(rec, path, issues),
730
735
  afterUserTurnKey: requireString(rec, "afterUserTurnKey", path, issues, TURN_KEY),
731
736
  ...timeoutMs === undefined ? {} : { timeoutMs },
732
737
  ...stallMs === undefined ? {} : { stallMs },
733
- ...stableMs === undefined ? {} : { stableMs }
738
+ ...stableMs === undefined ? {} : { stableMs },
739
+ ...stopOnApproval === undefined ? {} : { stopOnApproval }
740
+ };
741
+ },
742
+ "turns.approve": (raw, path, issues) => {
743
+ const rec = readObject(raw, path, issues);
744
+ return {
745
+ conversationId: readConversationId(rec, path, issues),
746
+ afterUserTurnKey: requireString(rec, "afterUserTurnKey", path, issues, TURN_KEY),
747
+ choice: requireLiteral(rec, "choice", path, issues, APPROVAL_CHOICES)
734
748
  };
735
749
  },
736
750
  "turns.read": (raw, path, issues) => {
@@ -846,6 +860,14 @@ var RESULT_READERS = {
846
860
  evidence: requireRecord(rec, "evidence", path, issues)
847
861
  };
848
862
  },
863
+ "turns.approve": (raw, path, issues) => {
864
+ const rec = readObject(raw, path, issues);
865
+ return {
866
+ clicked: requireBoolean(rec, "clicked", path, issues),
867
+ app: requireString(rec, "app", path, issues, LABEL),
868
+ evidence: requireRecord(rec, "evidence", path, issues)
869
+ };
870
+ },
849
871
  "turns.read": (raw, path, issues) => {
850
872
  const rec = readObject(raw, path, issues);
851
873
  const messageId = optionalString(rec, "messageId", path, issues, { maxLength: 256 });
@@ -1061,13 +1083,17 @@ var READERS = {
1061
1083
  },
1062
1084
  blobChunk: (raw, path, issues) => {
1063
1085
  const rec = readObject(raw, path, issues);
1086
+ const base64 = requireString(rec, "base64", path, issues, {
1087
+ pattern: /^[A-Za-z0-9+/]*={0,2}$/,
1088
+ maxLength: MAX_BLOB_CHUNK_BASE64
1089
+ });
1090
+ if (base64.length > 0 && base64DecodedLength(base64) === undefined) {
1091
+ fail(issues, at(path, "base64"), "must be padded base64");
1092
+ }
1064
1093
  return {
1065
1094
  blobId: requireString(rec, "blobId", path, issues, ID),
1066
1095
  offset: requireInt(rec, "offset", path, issues),
1067
- base64: requireString(rec, "base64", path, issues, {
1068
- pattern: /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/,
1069
- maxLength: MAX_BLOB_CHUNK_BASE64
1070
- })
1096
+ base64
1071
1097
  };
1072
1098
  },
1073
1099
  blobCommitResponse: (raw, path, issues) => {
@@ -2196,6 +2222,52 @@ function presentResponse(job) {
2196
2222
  };
2197
2223
  }
2198
2224
 
2225
+ // plugins/ask/approval.ts
2226
+ var APPROVAL_CHOICES2 = ["always", "once"];
2227
+ var MAX_APPROVALS = 10;
2228
+ function parseApproveApps(raw) {
2229
+ if (raw === undefined)
2230
+ return;
2231
+ const choice = APPROVAL_CHOICES2.find((known) => known === raw);
2232
+ if (choice === undefined) {
2233
+ throw failure("bad-request", `--approve-apps takes ${APPROVAL_CHOICES2.join(" or ")}`);
2234
+ }
2235
+ return choice;
2236
+ }
2237
+ async function waitReplyApproving(ctx, target, choice) {
2238
+ const params = {
2239
+ conversationId: target.conversationId,
2240
+ afterUserTurnKey: target.afterUserTurnKey,
2241
+ stopOnApproval: true
2242
+ };
2243
+ for (let answered = 0;; answered += 1) {
2244
+ try {
2245
+ return await ctx.ops.call("turns.waitReply", params);
2246
+ } catch (thrown) {
2247
+ const error = toBridgeError(thrown);
2248
+ if (error.code !== "approval-required")
2249
+ throw thrown;
2250
+ const app = typeof error.details?.app === "string" && error.details.app !== "" ? error.details.app : "one of its apps";
2251
+ if (choice === undefined) {
2252
+ throw failure("approval-required", `ChatGPT asks to allow ${app} before the reply goes on: answer it at ${target.url} and read the reply with \`voyager read\`, or ask with --approve-apps always`, error.details);
2253
+ }
2254
+ if (answered >= MAX_APPROVALS) {
2255
+ throw failure("approval-required", `ChatGPT asked to allow ${app} again after ${MAX_APPROVALS} answers`, error.details);
2256
+ }
2257
+ const approved = await ctx.ops.call("turns.approve", {
2258
+ conversationId: target.conversationId,
2259
+ afterUserTurnKey: target.afterUserTurnKey,
2260
+ choice
2261
+ });
2262
+ ctx.log.info("answered an app approval card", {
2263
+ app: approved.app,
2264
+ choice,
2265
+ clicked: approved.clicked
2266
+ });
2267
+ }
2268
+ }
2269
+ }
2270
+
2199
2271
  // plugins/ask/drive.ts
2200
2272
  import { execFile as execFile2 } from "node:child_process";
2201
2273
  import { randomBytes as randomBytes3 } from "node:crypto";
@@ -2430,6 +2502,33 @@ function checkRepoReach(target, result) {
2430
2502
  });
2431
2503
  }
2432
2504
 
2505
+ // plugins/ask/timebox.ts
2506
+ var SUGGESTED_TIMEBOX_MINUTES = 70;
2507
+ var MIN_MINUTES = 5;
2508
+ var MAX_MINUTES = 600;
2509
+ function parseTimebox(raw) {
2510
+ if (raw === undefined)
2511
+ return;
2512
+ const text = String(raw).trim().replace(/m$/i, "");
2513
+ const minutes = /^\d+$/.test(text) ? Number(text) : Number.NaN;
2514
+ if (!(minutes >= MIN_MINUTES && minutes <= MAX_MINUTES)) {
2515
+ throw failure("bad-request", `--timebox takes minutes from ${MIN_MINUTES} to ${MAX_MINUTES} (${SUGGESTED_TIMEBOX_MINUTES} for long Pro work), not ${JSON.stringify(String(raw))}`);
2516
+ }
2517
+ return minutes;
2518
+ }
2519
+ function timeboxPromptBlock(minutes) {
2520
+ return [
2521
+ `Time and wrap-up: a turn like this can lose its connection after about 80 minutes of work, and after that nothing is delivered and the sandbox files are lost. So please plan around a ${minutes}-minute countdown:`,
2522
+ `- When you start, note the time in your sandbox, and check it after each piece of work.`,
2523
+ `- When the ${minutes} minutes are up, start nothing new, wherever you are, and wrap up; leave about 10 minutes for that.`,
2524
+ `- Finish one piece completely before starting the next, so that a stop leaves whole pieces rather than many halves. If something still fails on the third try, set it aside, note it, and move on.`,
2525
+ `- If you make files, put them under /mnt/data/ and link them in your reply. Link each finished piece as soon as it is done, then one ZIP at the end with finished/ (work that passed your checks), unfinished/ (each with how far it got and what is missing) and METHOD.md (how you worked, how you checked, what did not work).`,
2526
+ `- If you use subagents, they keep the same countdown and hand back what they have before it ends.`,
2527
+ `- Open your reply with one line: finished N / unfinished M / about X minutes.`
2528
+ ].join(`
2529
+ `);
2530
+ }
2531
+
2433
2532
  // plugins/ask/index.ts
2434
2533
  var PHASE_C_OPTIONS = ["out"];
2435
2534
  function attachTimeoutMs(bytes) {
@@ -2484,9 +2583,16 @@ async function prepare(fg, argv) {
2484
2583
  dryRun: argv.options["dry-run"] === true
2485
2584
  });
2486
2585
  const repo = typeof argv.options.repo === "string" ? parseRepo(argv.options.repo) : undefined;
2586
+ const approveApps = parseApproveApps(argv.options["approve-apps"]);
2487
2587
  if (repo !== undefined)
2488
2588
  fg.note(`repo: ChatGPT is asked to write only to ${repo.branch}`);
2489
- const prompt = [asked, drive.block, repo === undefined ? "" : repoPromptBlock(repo)].filter((part) => part !== "").join(`
2589
+ const timebox = parseTimebox(argv.options.timebox);
2590
+ const prompt = [
2591
+ asked,
2592
+ drive.block,
2593
+ repo === undefined ? "" : repoPromptBlock(repo),
2594
+ timebox === undefined ? "" : timeboxPromptBlock(timebox)
2595
+ ].filter((part) => part !== "").join(`
2490
2596
 
2491
2597
  `);
2492
2598
  return {
@@ -2497,7 +2603,8 @@ async function prepare(fg, argv) {
2497
2603
  ...project === undefined ? {} : { project },
2498
2604
  ...conversationId === undefined ? {} : { conversationId },
2499
2605
  ...attachments.length > 0 ? { attachments } : {},
2500
- ...repo === undefined ? {} : { repo }
2606
+ ...repo === undefined ? {} : { repo },
2607
+ ...approveApps === undefined ? {} : { approveApps }
2501
2608
  };
2502
2609
  }
2503
2610
  function optionList(raw) {
@@ -2590,10 +2697,7 @@ ${preamble}`;
2590
2697
  url: sent.url,
2591
2698
  tabId: opened.tabId
2592
2699
  });
2593
- const reply = await ctx.ops.call("turns.waitReply", {
2594
- conversationId: sent.conversationId,
2595
- afterUserTurnKey: sent.userTurnKey
2596
- });
2700
+ const reply = await waitReplyApproving(ctx, { conversationId: sent.conversationId, afterUserTurnKey: sent.userTurnKey, url: sent.url }, input.approveApps);
2597
2701
  const repliedAt = Date.now();
2598
2702
  const read = await ctx.ops.call("turns.read", {
2599
2703
  conversationId: sent.conversationId,
@@ -2681,11 +2785,19 @@ var askPlugin = definePlugin({
2681
2785
  multiple: true,
2682
2786
  summary: "file or folder to attach (repeatable; folders are zipped without credentials)"
2683
2787
  },
2788
+ timebox: {
2789
+ type: "string",
2790
+ summary: "ask ChatGPT to wrap up and hand over what it has after this many minutes (70 for long Pro sandbox work)"
2791
+ },
2684
2792
  "dry-run": {
2685
2793
  type: "boolean",
2686
2794
  summary: "pack the attachments and print what would be sent, without sending"
2687
2795
  },
2688
2796
  out: { type: "string", summary: "also copy the outputs to this folder (Phase C)" },
2797
+ "approve-apps": {
2798
+ type: "string",
2799
+ summary: "answer ChatGPT's app approval card (Google Drive, GitHub…) mid-reply: always (its Always allow, kept in your ChatGPT settings) or once; without it the job stops there (exit 3)"
2800
+ },
2689
2801
  "no-files": {
2690
2802
  type: "boolean",
2691
2803
  summary: "do not download the files the reply offers (saved under files/ otherwise)"
@@ -3099,7 +3211,7 @@ class PluginRegistry {
3099
3211
  // package.json
3100
3212
  var package_default = {
3101
3213
  name: "@voyager-crew/cli",
3102
- version: "0.3.0",
3214
+ version: "0.4.0",
3103
3215
  description: "Ask ChatGPT from your terminal or your coding agent, through the Voyager browser extension",
3104
3216
  keywords: [
3105
3217
  "chatgpt",
@@ -3141,11 +3253,12 @@ var package_default = {
3141
3253
  format: "oxfmt",
3142
3254
  "format:check": "oxfmt --check",
3143
3255
  verify: "bun run format:check && bun run lint:check && bun run typecheck && bun run test",
3144
- prepublishOnly: "bun run verify && bun run build"
3256
+ prepublishOnly: "bun run verify && bun run build",
3257
+ prepare: "node scripts/install-git-hooks.cjs"
3145
3258
  },
3146
3259
  devDependencies: {
3147
3260
  "@types/node": "^24.9.0",
3148
- "@voyager-crew/bridge-protocol": "^0.3.0",
3261
+ "@voyager-crew/bridge-protocol": "^0.4.0",
3149
3262
  fflate: "0.8.2",
3150
3263
  oxfmt: "^0.65.0",
3151
3264
  oxlint: "^1.80.0",
@@ -4445,6 +4558,7 @@ var DEFAULT_OP_TIMEOUT_MS = {
4445
4558
  "composer.attach": 120000,
4446
4559
  "composer.send": 30000,
4447
4560
  "turns.read": 30000,
4561
+ "turns.approve": 30000,
4448
4562
  "files.download": 10 * 60000,
4449
4563
  "project.list": 20000,
4450
4564
  "project.create": 45000,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@voyager-crew/cli",
3
- "version": "0.3.0",
3
+ "version": "0.4.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.4.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,17 +86,30 @@ 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 |
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: another job runs (`error.details.activeJobId`) | 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 |
98
113
 
99
114
  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.
100
115