@mergeline/agent 0.5.4 → 0.6.1

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
@@ -18,6 +18,7 @@ committing. Nothing technical is needed from the person.
18
18
  npx -y @mergeline/agent init --claude --url https://acme.mergeline.app # once per repository; commit what it adds
19
19
  npx -y @mergeline/agent login fe-1 --url https://acme.mergeline.app --key ab_... # once per agent and machine
20
20
  npx -y @mergeline/agent start fe-1 # every session; then /pick
21
+ npx -y @mergeline/agent watch --agent fe-1 --engine claude --follow # or unattended: the worker
21
22
  ```
22
23
 
23
24
  `init --url` writes the board's address into `.mergeline.json` (no
@@ -127,8 +128,117 @@ MCP config (Claude Code `--mcp-config`, Codex, other MCP clients):
127
128
  }
128
129
  ```
129
130
 
130
- Run the agent whenever its queue has work (on your machine, with your AI
131
- account; one run at a time):
131
+ ### Unattended: the worker, `board watch --engine`
132
+
133
+ To let an agent work through its queue with nobody at the keyboard, run the
134
+ worker in the repository's main checkout (not a linked worktree). It does
135
+ the board's part of every ticket itself (claim, heartbeats, push, the PR,
136
+ submit, ask or release) and lets the engine, Claude Code or Codex, only
137
+ write the code. How to pay for those runs, per provider:
138
+ [docs/unattended.md](https://github.com/mergeline/mergeline/blob/main/docs/unattended.md).
139
+
140
+ ```sh
141
+ board watch --agent fe-1 --engine claude # until the queue is empty
142
+ board watch --agent fe-1 --engine claude --follow # keep waiting for new tickets
143
+ board watch --agent fe-1 --engine claude -- --model opus # more arguments for the engine
144
+ board watch --agent fe-1 --engine codex # Codex CLI instead of Claude Code
145
+ board watch --agent fe-1 --engine codex -- -m <model> # arguments for codex exec
146
+ ```
147
+
148
+ For each ticket it claims, it reads the spec from `origin/main`, makes a
149
+ fresh worktree at `../.wt/<ticket>` (from `origin/<branch>` when the branch
150
+ is on origin, else from `origin/main`) and writes the ticket to
151
+ `.mergeline-run/ticket.md` there (git ignores the folder). The engine
152
+ (`claude -p`, or `codex exec --json`, with the package's own prompt,
153
+ `engine/prompt.md`) writes a
154
+ plan, progress lines and, last, `.mergeline-run/result.json`: done, a
155
+ question, or a release. The worker heartbeats, commits what the engine left
156
+ uncommitted, runs the repository's `test` command when `.mergeline.json` on
157
+ `main` has one (`"test": "npm test"`, added by hand), pushes, opens or
158
+ reuses the PR with `gh`, and submits; or pushes the work so far and asks;
159
+ or releases. Then it removes the worktree and the local branch.
160
+
161
+ What the engine left uncommitted is committed with a subject from what it
162
+ said: `<ticket>: <the first sentence of its summary>` (72 characters at
163
+ most) and the whole summary in the body; before a question,
164
+ `<ticket>: work so far, before a question` with the question in the body.
165
+ The body's last line says the worker committed it and which engine left it.
166
+ The engine's own commits are not touched.
167
+
168
+ The engine never gets the agent key: its environment has no `BOARD_*`, no
169
+ GitHub token and no SSH agent, Claude Code starts with no MCP server
170
+ (`--strict-mcp-config`) and with the kit's rules plus deny rules for
171
+ `board`, `git push`, `gh` and `git config` on its command line, and
172
+ `git push origin` fails inside it (a push to any other repository works,
173
+ so tests that push to their own throwaway `origin` run). What the worker
174
+ does not stop: the engine runs as the same OS user, so it can read that
175
+ user's files (the keys `board login` saved, an SSH key without a
176
+ passphrase, `gh`'s own config) and push with a URL of its own. Running the
177
+ engine as another user or in a container is a later round's; for Claude
178
+ Code, its deny rules are the second fence for that (the board's
179
+ `docs/security.md`).
180
+
181
+ Claude Code needs no folder trust for the worker: its rules are on the
182
+ command line. Each run logs `Ignoring <n> permissions.allow entries from
183
+ .claude/settings.json: this workspace has not been trusted`; that is
184
+ expected, since the worktree is a folder Claude Code has not trusted, and
185
+ the run's own rules apply instead.
186
+
187
+ Codex runs in its own `workspace-write` sandbox with the network on (for
188
+ `npm ci` and the like; npm's cache goes to a temporary folder of the run),
189
+ approval `never`, and every MCP server of `codex mcp list` turned off with
190
+ `-c` (the board's too: Codex gives an MCP server `HOME`, where the saved key
191
+ is). Its sandbox does not let it commit in a linked worktree, so the worker
192
+ commits what it wrote. An MCP server whose name `-c` cannot address (not
193
+ letters, digits, `_` and `-`) stops the run: rename it.
194
+
195
+ The usage the worker reports: for Claude Code, its tokens and cost; for
196
+ Codex, the tokens of every turn (`input_tokens` without the cached input,
197
+ which is `cache_read_tokens`) and no cost, `source: "codex"`.
198
+
199
+ The flags: `--engine claude|codex`; `--follow` keeps waiting for new
200
+ tickets, checking every `--interval <s>` (default 30); `--max-runs <n>`
201
+ (default 10) is the most tickets one start takes; `--timeout <min>`
202
+ (default 90) is the most one engine run may take; what follows `--` is
203
+ added to the engine's command line. It stops when the queue is empty
204
+ (unless `--follow`), after `--max-runs` tickets, or after 3 failed runs
205
+ (releases) in a row; after a failed run it waits `--interval` before
206
+ claiming again. Ctrl+C while the engine runs releases
207
+ the ticket. A worker killed outright leaves its ticket In progress; a new
208
+ one waits, claiming every `--interval`, until the board lets it resume (5
209
+ silent minutes), and starts again from what origin has.
210
+
211
+ A running worker keeps the package it started with: a worker started with
212
+ `--follow` runs every later ticket with that code and that engine prompt.
213
+ After upgrading the package (or rebuilding it from a checkout), stop the
214
+ worker with Ctrl+C while it is not running an engine (it is waiting for a
215
+ ticket), and start it again.
216
+
217
+ Commits of a run that origin does not have are kept, never lost: a run
218
+ that ends without pushing (released by the engine or the worker, a question
219
+ after a push that failed) keeps them as it deletes its local branch, and a
220
+ worker killed outright or stopped by a config change has them kept by the
221
+ next start, before it resets the branch. They go under
222
+ `refs/mergeline/kept/<ticket>/<UTC time>`, with a log line. They are not used, merged or pushed, and the worker never deletes
223
+ them; uncommitted changes in a stale worktree are not kept. List them with
224
+ `git for-each-ref refs/mergeline/kept`, look at one with `git log <ref>`,
225
+ and remove it with `git update-ref -d <ref>`.
226
+
227
+ The worker compares the main checkout's git config (and your global one)
228
+ before and after every git command it runs once the engine has started.
229
+ Changing it while a worker runs stops the worker: the engine, or you
230
+ (`git config`, `git push -u`, `git branch -D` of a branch with an upstream).
231
+ The run is released with nothing pushed, the log names the keys added,
232
+ removed or changed (never their values), and the worktree is left for you
233
+ to inspect.
234
+
235
+ ### Any other tool: `board watch -- <command>`
236
+
237
+ The command form runs any tool whenever the agent's queue has work (on
238
+ your machine, with your AI account; one run at a time); the tool does the
239
+ board's part itself with the kit's `/pick` and `/done`. For Claude Code
240
+ and Codex the worker above is the way; the form with them, as it was
241
+ before the worker:
132
242
 
133
243
  ```sh
134
244
  board watch --agent fe-1 --usage-from claude-json -- \
@@ -162,7 +272,11 @@ failed: <its message>`.
162
272
  A board that is paused (asleep until a person opens it; it answers HTTP 503
163
273
  with `{"code": "board_paused"}`) is not a failure: tools and commands say
164
274
  "board paused: ...", and `watch` waits, checking every `--interval`, then
165
- goes on.
275
+ goes on. So is a board `watch` cannot reach for a while (no answer, HTTP
276
+ 502, 504, a 503 that is not a pause, 429) once it has logged in: it logs
277
+ `board not reachable (...); retrying every <s>s`, then `the board is back`,
278
+ with no limit on how long. A board it cannot reach when it starts is
279
+ reported at once (exit 1), so a wrong address is not waited for.
166
280
 
167
281
  Commands: `init`, `watch`, `whoami`, `list`, `claim`, `heartbeat <ticket> [note]`,
168
282
  `log <ticket> <plan|progress|warn> <text>`, `record-spec <ticket> <sha>`,
package/dist/cli.js CHANGED
@@ -28,6 +28,8 @@ import { join, resolve } from "node:path";
28
28
  import { init } from "./init.js";
29
29
  import { runMcpServer } from "./mcp.js";
30
30
  import { watch } from "./watch.js";
31
+ import { enginePrompt, ENGINES } from "./engines.js";
32
+ import { mainCheckout, work } from "./worker.js";
31
33
  import { forgetAgent, pickSaved, saveAgent, savedAgents } from "./credentials.js";
32
34
  import { agentCredentialsFromEnv } from "./pb.js";
33
35
  import { boardInContext, normalizeBoardUrl, REPO_FILE } from "./repo.js";
@@ -64,6 +66,15 @@ Usage:
64
66
  after --max-runs (default 10), after 2 runs that changed
65
67
  nothing or 3 failed runs in a row. --usage-from claude-json
66
68
  reports each run's tokens and cost from Claude Code's JSON
69
+ board watch --engine <name> [--follow] [--interval <s>] [--max-runs <n>] [--timeout <min>] [-- <engine args...>]
70
+ the worker: run in the repository's main checkout, it does
71
+ the board's part itself (claim, the spec, a fresh worktree in
72
+ ../.wt/<ticket>, push, the PR, submit, ask or release) and the
73
+ engine only writes the code, without the agent key. Engines:
74
+ claude, codex. --timeout: the most one engine run may take (default
75
+ 90). What follows -- is added to the engine's command line.
76
+ Stops when the queue is empty (unless --follow), after
77
+ --max-runs tickets, or after 3 failed runs in a row
67
78
  board whoami check the connection and show the agent
68
79
  board list tickets assigned to you that are not done
69
80
  board claim take your next ticket (or {"ticket": null})
@@ -321,10 +332,7 @@ async function main(argvIn) {
321
332
  case "watch": {
322
333
  const sep = rawArgs.indexOf("--");
323
334
  const opts = sep < 0 ? rawArgs : rawArgs.slice(0, sep);
324
- const agentCommand = sep < 0 ? [] : rawArgs.slice(sep + 1);
325
- if (agentCommand.length === 0) {
326
- throw new UsageError('board watch needs the agent command after --, e.g. board watch -- claude -p "/pick"');
327
- }
335
+ const after = sep < 0 ? [] : rawArgs.slice(sep + 1);
328
336
  const num = (flag, fallback) => {
329
337
  const i = opts.indexOf(flag);
330
338
  if (i < 0)
@@ -334,23 +342,59 @@ async function main(argvIn) {
334
342
  throw new UsageError(`${flag} needs a whole number, 1 or more`);
335
343
  return n;
336
344
  };
337
- const known = new Set(["--follow", "--interval", "--max-runs", "--usage-from"]);
338
- const valued = ["--interval", "--max-runs", "--usage-from"];
345
+ const known = new Set(["--follow", "--interval", "--max-runs", "--usage-from", "--engine", "--timeout"]);
346
+ const valued = ["--interval", "--max-runs", "--usage-from", "--engine", "--timeout"];
339
347
  const unknown = opts.find((a, i) => a.startsWith("--") && !known.has(a) && !valued.includes(opts[i - 1] ?? ""));
340
- const ui = opts.indexOf("--usage-from");
341
- const usageFrom = ui < 0 ? undefined : opts[ui + 1];
342
- if (ui >= 0 && usageFrom !== "claude-json")
343
- throw new UsageError("--usage-from supports claude-json (claude -p --output-format json)");
344
348
  if (unknown)
345
349
  throw new UsageError(`unknown option ${unknown}; run board help`);
346
- const code = await watch({
347
- board: board(fixed || undefined),
348
- command: agentCommand,
350
+ const ui = opts.indexOf("--usage-from");
351
+ const usageFrom = ui < 0 ? undefined : opts[ui + 1];
352
+ const engineName = option(opts, "--engine");
353
+ const common = {
349
354
  maxRuns: num("--max-runs", 10),
350
355
  follow: opts.includes("--follow"),
351
356
  intervalSec: num("--interval", 30),
352
357
  lockFile: file.replace(/session-([^/\\]+)\.json$/, "watch-$1.lock"),
353
358
  log: (line) => process.stderr.write(`board watch: ${terminalLine(line)}\n`),
359
+ };
360
+ if (engineName !== undefined) {
361
+ const engine = Object.hasOwn(ENGINES, engineName) ? ENGINES[engineName] : undefined;
362
+ if (!engine)
363
+ throw new UsageError(`unknown engine ${terminalJson(engineName)}; engines: ${Object.keys(ENGINES).join(", ")}`);
364
+ if (ui >= 0)
365
+ throw new UsageError("--usage-from is for the command mode; with --engine the worker reads the engine's usage itself");
366
+ const checkout = mainCheckout(process.cwd());
367
+ if ("error" in checkout)
368
+ throw new UsageError(checkout.error);
369
+ const envSec = (name) => {
370
+ const n = Number(process.env[name]);
371
+ return Number.isFinite(n) && n > 0 ? n : undefined;
372
+ };
373
+ const code = await work({
374
+ ...common,
375
+ board: board(fixed || undefined),
376
+ engine,
377
+ engineArgs: after,
378
+ prompt: enginePrompt(),
379
+ repo: checkout.repo,
380
+ // BOARD_WATCH_*: for tests only (not in board help).
381
+ timeoutSec: envSec("BOARD_WATCH_TIMEOUT_SEC") ?? num("--timeout", 90) * 60,
382
+ beatSec: envSec("BOARD_WATCH_BEAT_SEC") ?? 120,
383
+ });
384
+ process.exitCode = code;
385
+ return undefined;
386
+ }
387
+ if (opts.includes("--timeout"))
388
+ throw new UsageError("--timeout is for the worker only: board watch --engine <name> --timeout <min>");
389
+ if (after.length === 0) {
390
+ throw new UsageError('board watch needs the agent command after --, e.g. board watch -- claude -p "/pick", or --engine claude');
391
+ }
392
+ if (ui >= 0 && usageFrom !== "claude-json")
393
+ throw new UsageError("--usage-from supports claude-json (claude -p --output-format json)");
394
+ const code = await watch({
395
+ ...common,
396
+ board: board(fixed || undefined),
397
+ command: after,
354
398
  usageFrom: usageFrom,
355
399
  });
356
400
  process.exitCode = code;
@@ -0,0 +1,126 @@
1
+ // Engines for `board watch --engine <name>` (worker.ts): the tool that writes
2
+ // the code for one ticket. An adapter knows the engine's command line, how to
3
+ // pass it the prompt, and how to read its usage and its error from what it
4
+ // printed. The worker does everything that touches the board or origin.
5
+ import { spawnSync } from "node:child_process";
6
+ import { readFileSync } from "node:fs";
7
+ import { join } from "node:path";
8
+ import { PACKAGE_NAME } from "./init.js";
9
+ import { errorFromClaudeJson, errorFromCodexJson, usageFromClaudeJson, usageFromCodexJson } from "./watch.js";
10
+ /** The prompt every engine gets (agent/engine/prompt.md). */
11
+ export function enginePrompt() {
12
+ return readFileSync(new URL("../engine/prompt.md", import.meta.url), "utf8");
13
+ }
14
+ /**
15
+ * Allow rules of the kit the engine must not get: everything that reaches
16
+ * the board, origin or GitHub is the worker's.
17
+ */
18
+ function dropFromAllow(rule) {
19
+ return /^mcp__board__/.test(rule) ||
20
+ /^Bash\(board[ )]/.test(rule) ||
21
+ rule.includes(PACKAGE_NAME) ||
22
+ /^Bash\(git push[ )]/.test(rule) ||
23
+ /^Bash\(gh[ )]/.test(rule);
24
+ }
25
+ /** Deny rules the engine gets on top of the kit's. */
26
+ export const ENGINE_DENY = [
27
+ "Bash(board *)",
28
+ `Bash(*${PACKAGE_NAME}*)`,
29
+ "Bash(git push*)",
30
+ "Bash(gh *)",
31
+ "Bash(git config*)",
32
+ "mcp__board__*",
33
+ ];
34
+ /** Claude Code's permission rules for an engine run: the kit's, with its placeholders filled as `board init` fills them, fenced. */
35
+ export function claudeRules() {
36
+ const raw = readFileSync(new URL("../kit/claude-settings.json", import.meta.url), "utf8").replaceAll("{{package}}", PACKAGE_NAME);
37
+ const { allow = [], deny = [] } = JSON.parse(raw).permissions;
38
+ return {
39
+ allow: allow.filter((r) => !dropFromAllow(r)),
40
+ deny: [...deny, ...ENGINE_DENY.filter((r) => !deny.includes(r))],
41
+ };
42
+ }
43
+ const claude = {
44
+ name: "claude",
45
+ command(prompt, extra) {
46
+ const { allow, deny } = claudeRules();
47
+ return {
48
+ cmd: "claude",
49
+ args: [
50
+ "-p", prompt,
51
+ "--output-format", "json",
52
+ "--permission-mode", "auto",
53
+ "--setting-sources", "project,local",
54
+ // With no --mcp-config: no MCP server at all, the board's included.
55
+ "--strict-mcp-config",
56
+ "--allowedTools", ...allow,
57
+ "--disallowedTools", ...deny,
58
+ ...extra,
59
+ ],
60
+ };
61
+ },
62
+ usage: usageFromClaudeJson,
63
+ error: errorFromClaudeJson,
64
+ };
65
+ /** A name `-c mcp_servers.<name>...` can address (a TOML bare key). */
66
+ const BARE_KEY = /^[A-Za-z0-9_-]+$/;
67
+ /**
68
+ * The MCP servers Codex would start in this folder (`codex mcp list --json`:
69
+ * ~/.codex/config.toml and the project's). Codex starts a server with HOME and
70
+ * not BOARD_CONFIG_DIR, so a board server under any name would find the saved
71
+ * key: every one is turned off. When Codex cannot list them the run does not
72
+ * start (the worker releases with the reason): one left on could be the board's.
73
+ */
74
+ export function codexMcpServers(run) {
75
+ const r = spawnSync("codex", ["mcp", "list", "--json"], { cwd: run.cwd, env: run.env, encoding: "utf8", timeout: 30_000 });
76
+ const cannot = (why) => new Error(`board watch cannot list Codex's MCP servers (codex mcp list --json: ${why.replace(/\s+/g, " ").trim().slice(0, 300)}), so it cannot turn them off for the run`);
77
+ if (r.error)
78
+ throw cannot(r.error.message);
79
+ if (r.status !== 0)
80
+ throw cannot(r.stderr || `exit ${r.status ?? r.signal}`);
81
+ let list;
82
+ try {
83
+ list = JSON.parse(r.stdout);
84
+ }
85
+ catch {
86
+ throw cannot("its output is not JSON");
87
+ }
88
+ if (!Array.isArray(list))
89
+ throw cannot("its output is not a list");
90
+ return list.map((s) => {
91
+ const name = s && typeof s === "object" ? s.name : undefined;
92
+ if (typeof name !== "string")
93
+ throw cannot("a server without a name");
94
+ return name;
95
+ });
96
+ }
97
+ /** Codex's `-c` overrides for an engine run, after `codex exec` (round 8, R5). */
98
+ export function codexOverrides(servers, scratch) {
99
+ const odd = servers.find((n) => !BARE_KEY.test(n));
100
+ if (odd !== undefined) {
101
+ throw new Error(`Codex has an MCP server named ${JSON.stringify(odd)}, which board watch cannot turn off for the run; rename it in ~/.codex/config.toml to letters, digits, _ and -`);
102
+ }
103
+ return [
104
+ // The board's server, as the Connect window adds it, replaced and off; present or not.
105
+ "-c", 'mcp_servers.board={command="false",args=[],enabled=false}',
106
+ ...servers.filter((n) => n !== "board").flatMap((n) => ["-c", `mcp_servers.${n}.enabled=false`]),
107
+ // The worktree is writable; the network is on for installs; no approval to wait for.
108
+ "--sandbox", "workspace-write",
109
+ "-c", "sandbox_workspace_write.network_access=true",
110
+ "-c", 'approval_policy="never"',
111
+ // npm's cache in ~/.npm is outside the sandbox's writable folders.
112
+ "-c", `shell_environment_policy.set.npm_config_cache=${JSON.stringify(join(scratch, "npm-cache"))}`,
113
+ ];
114
+ }
115
+ const codex = {
116
+ name: "codex",
117
+ command(prompt, extra, run) {
118
+ return {
119
+ cmd: "codex",
120
+ args: ["exec", "--json", ...codexOverrides(codexMcpServers(run), run.scratch), ...extra, "--", prompt],
121
+ };
122
+ },
123
+ usage: usageFromCodexJson,
124
+ error: errorFromCodexJson,
125
+ };
126
+ export const ENGINES = { claude, codex };
package/dist/repo.js CHANGED
@@ -50,7 +50,7 @@ export function readRepoFile(file) {
50
50
  catch {
51
51
  throw new Error(`${file} is not valid JSON; run board init --url <board> to write it again`);
52
52
  }
53
- const { board, kit } = (data ?? {});
53
+ const { board, kit, test } = (data ?? {});
54
54
  const out = {};
55
55
  if (board !== undefined) {
56
56
  if (typeof board !== "string" || !board)
@@ -64,6 +64,8 @@ export function readRepoFile(file) {
64
64
  }
65
65
  if (typeof kit === "number" && Number.isInteger(kit))
66
66
  out.kit = kit;
67
+ if (typeof test === "string" && test.trim())
68
+ out.test = test.trim();
67
69
  return out;
68
70
  }
69
71
  /** The kit version of the repository around cwd, or undefined (no file, no version, or a broken file). */
package/dist/service.js CHANGED
@@ -26,13 +26,23 @@ export class BoardPaused extends BoardError {
26
26
  this.name = "BoardPaused";
27
27
  }
28
28
  }
29
+ /**
30
+ * The board gave no answer at all (the network, a sleeping Mac, a board that
31
+ * is not running). `board watch` waits this out after its first contact.
32
+ */
33
+ export class BoardUnreachable extends BoardError {
34
+ constructor(message) {
35
+ super(message, 0);
36
+ this.name = "BoardUnreachable";
37
+ }
38
+ }
29
39
  const SUMMARY_FIELDS = "id,title,status,priority,spec_path,branch,pr_url,claimed_until,attempts,block_kind,block_text";
30
40
  function toBoardError(err, url, action) {
31
41
  if (err instanceof BoardError)
32
42
  return err;
33
43
  if (err instanceof ClientResponseError) {
34
44
  if (err.status === 0) {
35
- return new BoardError(`board is not reachable at ${url}; is PocketBase running?`);
45
+ return new BoardUnreachable(`board is not reachable at ${url}; is PocketBase running?`);
36
46
  }
37
47
  const response = (err.response ?? {});
38
48
  if (err.status === 503 && response.code === "board_paused") {
@@ -132,10 +142,18 @@ export class TicketService {
132
142
  return records;
133
143
  });
134
144
  }
135
- /** Carries this package's version and the repository's kit version (repo.ts), so the board can say when the kit is old. */
136
- claim() {
145
+ /**
146
+ * Carries this package's version and the repository's kit version (repo.ts), so the board can say when the kit is old.
147
+ * A worker (`board watch --engine`) also passes runner "worker" and its engine, so its runs tell from a person's session.
148
+ */
149
+ claim(run = {}) {
137
150
  const kit = repoKit();
138
- return this.post("claim", { client: PACKAGE_VERSION, ...(kit === undefined ? {} : { kit }) });
151
+ return this.post("claim", {
152
+ client: PACKAGE_VERSION,
153
+ ...(kit === undefined ? {} : { kit }),
154
+ ...(run.runner === undefined ? {} : { runner: run.runner }),
155
+ ...(run.engine === undefined ? {} : { engine: run.engine }),
156
+ });
139
157
  }
140
158
  heartbeat(ticketId, note) {
141
159
  return this.post("heartbeat", { ticket_id: ticketId, note: note ?? "" });
@@ -297,6 +315,13 @@ export class BoardAdmin {
297
315
  sort: "created",
298
316
  }));
299
317
  }
318
+ /** The ticket's runs, oldest first. */
319
+ listRuns(ticketId) {
320
+ return this.call("list runs", () => this.pb.collection("runs").getFullList({
321
+ filter: this.pb.filter("ticket = {:id}", { id: ticketId }),
322
+ sort: "started,attempt",
323
+ }));
324
+ }
300
325
  /** Deletes every ticket (events cascade). */
301
326
  deleteAllTickets() {
302
327
  return this.call("delete tickets", async () => {
package/dist/watch.js CHANGED
@@ -12,12 +12,14 @@
12
12
  // non-zero the stop says they failed instead), or
13
13
  // - the command failed three times in a row.
14
14
  // A paused board (asleep until a person opens it) is not a failure: the
15
- // watcher waits, checking every --interval, and goes on when it is back.
15
+ // watcher waits, checking every --interval, and goes on when it is back. So
16
+ // is a board it cannot reach (no answer, 502, 504, a 503 that is not a pause,
17
+ // 429), after the first contact: a wrong address is reported at once.
16
18
  // One watcher per agent and machine: a lock file in the state directory.
17
19
  import { spawn } from "node:child_process";
18
20
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
19
21
  import { dirname } from "node:path";
20
- import { BoardError, BoardPaused } from "./service.js";
22
+ import { BoardError, BoardPaused, BoardUnreachable } from "./service.js";
21
23
  /** Usage from Claude Code's final JSON (`claude -p --output-format json`), or null. */
22
24
  export function usageFromClaudeJson(output) {
23
25
  const candidates = [output.trim(), ...output.trim().split("\n").reverse()];
@@ -87,6 +89,69 @@ export function errorFromClaudeJson(output) {
87
89
  return null;
88
90
  }
89
91
  const ERROR_CHARS = 300;
92
+ /** Codex's `--json` events (JSONL), the ones that parse as objects. */
93
+ function codexEvents(output) {
94
+ const events = [];
95
+ for (const line of output.split("\n")) {
96
+ const text = line.trim();
97
+ if (!text.startsWith("{"))
98
+ continue;
99
+ try {
100
+ const e = JSON.parse(text);
101
+ if (e && typeof e === "object" && typeof e.type === "string")
102
+ events.push(e);
103
+ }
104
+ catch {
105
+ // not an event
106
+ }
107
+ }
108
+ return events;
109
+ }
110
+ /**
111
+ * Usage from `codex exec --json`: the tokens of every `turn.completed`, summed.
112
+ * OpenAI counts cached input inside `input_tokens`; here `input_tokens` is
113
+ * without it and `cache_read_tokens` is it, as for Claude Code. Codex prints
114
+ * no cost. Null when no turn completed.
115
+ */
116
+ export function usageFromCodexJson(output) {
117
+ const turns = codexEvents(output).filter((e) => e.type === "turn.completed" && e.usage && typeof e.usage === "object");
118
+ if (!turns.length)
119
+ return null;
120
+ const sum = (field) => {
121
+ const counts = turns.map((t) => t.usage[field]).filter((n) => Number.isInteger(n) && n >= 0);
122
+ return counts.length ? counts.reduce((a, b) => a + b, 0) : undefined;
123
+ };
124
+ const input = sum("input_tokens");
125
+ const cached = sum("cached_input_tokens");
126
+ const output_tokens = sum("output_tokens");
127
+ const usage = { source: "codex" };
128
+ if (input !== undefined)
129
+ usage.input_tokens = Math.max(0, input - (cached ?? 0));
130
+ if (output_tokens !== undefined)
131
+ usage.output_tokens = output_tokens;
132
+ if (cached !== undefined)
133
+ usage.cache_read_tokens = cached;
134
+ return usage;
135
+ }
136
+ /**
137
+ * The error a `codex exec --json` run ended with, one line, at most 300
138
+ * characters: the last `turn.failed`, else the last `error` event that is not
139
+ * a retry. Null when it reports none.
140
+ */
141
+ export function errorFromCodexJson(output) {
142
+ const events = codexEvents(output);
143
+ const message = (e) => {
144
+ const m = e.type === "turn.failed" ? e.error?.message : e.message;
145
+ return typeof m === "string" && m.trim() ? m : null;
146
+ };
147
+ const failed = events.filter((e) => e.type === "turn.failed").map(message).filter((m) => m !== null);
148
+ const errors = events.filter((e) => e.type === "error").map(message).filter((m) => m !== null && !/^Reconnecting\b/.test(m));
149
+ const said = failed.at(-1) ?? errors.at(-1);
150
+ if (!said)
151
+ return null;
152
+ const line = said.replace(/\s+/g, " ").trim();
153
+ return line.length > ERROR_CHARS ? `${line.slice(0, ERROR_CHARS)}...` : line;
154
+ }
90
155
  /**
91
156
  * The ticket a run worked on, for its usage. Only a ticket the agent could
92
157
  * take when the run started counts (ready or in progress then): what a human
@@ -103,7 +168,7 @@ export function workedOn(before, after) {
103
168
  return before.find((t) => t.status === "in_progress") ?? null;
104
169
  return null;
105
170
  }
106
- const label = (t) => /^T-\d+/.exec(t.title)?.[0] ?? t.id;
171
+ export const label = (t) => /^T-\d+/.exec(t.title)?.[0] ?? t.id;
107
172
  const NO_PROGRESS_STOP = 2;
108
173
  const FAILURE_STOP = 3;
109
174
  export function hasWork(mine) {
@@ -125,7 +190,7 @@ function alive(pid) {
125
190
  return false;
126
191
  }
127
192
  }
128
- function takeLock(file) {
193
+ export function takeLock(file) {
129
194
  try {
130
195
  const pid = Number(JSON.parse(readFileSync(file, "utf8")).pid);
131
196
  if (pid && pid !== process.pid && alive(pid)) {
@@ -139,7 +204,7 @@ function takeLock(file) {
139
204
  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
140
205
  writeFileSync(file, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + "\n", { mode: 0o600 });
141
206
  }
142
- function sleep(ms, stop) {
207
+ export function sleep(ms, stop) {
143
208
  return new Promise((resolve) => {
144
209
  const step = 250;
145
210
  let left = ms;
@@ -152,6 +217,48 @@ function sleep(ms, stop) {
152
217
  tick();
153
218
  });
154
219
  }
220
+ /**
221
+ * A board that cannot be reached for now: no answer at all, a proxy's 502,
222
+ * 503 (not a pause) or 504, or the board's rate limit (429). Every other
223
+ * error means what it says.
224
+ */
225
+ export function isUnreachable(err) {
226
+ if (err instanceof BoardPaused)
227
+ return false;
228
+ if (err instanceof BoardUnreachable)
229
+ return true;
230
+ return err instanceof BoardError && [429, 502, 503, 504].includes(err.status);
231
+ }
232
+ /**
233
+ * fn's result once the board answers: while it is paused or (unless strict)
234
+ * cannot be reached, waits intervalSec and tries again, with no limit. Logs
235
+ * once per outage and once when the board is back. Null when stopped while
236
+ * waiting; any other error is thrown.
237
+ */
238
+ export async function untilAnswered(fn, o) {
239
+ let waiting = null;
240
+ while (!o.stop.stopped) {
241
+ try {
242
+ const result = await fn();
243
+ if (waiting)
244
+ o.log("the board is back");
245
+ return result;
246
+ }
247
+ catch (err) {
248
+ const kind = err instanceof BoardPaused ? "paused" : !o.strict && isUnreachable(err) ? "unreachable" : null;
249
+ if (!kind)
250
+ throw err;
251
+ if (kind !== waiting) {
252
+ o.log(kind === "paused"
253
+ ? `${err.message}; waiting, checking every ${o.intervalSec}s (Ctrl+C to stop)`
254
+ : `board not reachable (${err.message}); retrying every ${o.intervalSec}s (Ctrl+C to stop)`);
255
+ }
256
+ waiting = kind;
257
+ await sleep(o.intervalSec * 1000, o.stop);
258
+ }
259
+ }
260
+ return null;
261
+ }
155
262
  /** Runs the watcher until a stop condition; returns the exit code for the CLI. */
156
263
  export async function watch(opts) {
157
264
  const { board, command, log } = opts;
@@ -166,27 +273,8 @@ export async function watch(opts) {
166
273
  };
167
274
  process.on("SIGINT", onSignal);
168
275
  process.on("SIGTERM", onSignal);
169
- /** fn's result once the board answers; null when stopped while it was paused. */
170
- const whenAwake = async (fn) => {
171
- let paused = false;
172
- while (!state.stopped) {
173
- try {
174
- const result = await fn();
175
- if (paused)
176
- log("the board is back");
177
- return result;
178
- }
179
- catch (err) {
180
- if (!(err instanceof BoardPaused))
181
- throw err;
182
- if (!paused)
183
- log(`${err.message}; waiting, checking every ${opts.intervalSec}s (Ctrl+C to stop)`);
184
- paused = true;
185
- await sleep(opts.intervalSec * 1000, state);
186
- }
187
- }
188
- return null;
189
- };
276
+ /** fn's result once the board answers; null when stopped while waiting for it. */
277
+ const whenAwake = (fn, strict = false) => untilAnswered(fn, { intervalSec: opts.intervalSec, log, stop: state, strict });
190
278
  let runs = 0;
191
279
  let noProgress = 0;
192
280
  /** Exit codes of the runs counted in noProgress. */
@@ -194,7 +282,7 @@ export async function watch(opts) {
194
282
  let failures = 0;
195
283
  let waitingLogged = false;
196
284
  try {
197
- if ((await whenAwake(() => board.login())) === null)
285
+ if ((await whenAwake(() => board.login(), true)) === null)
198
286
  return 0;
199
287
  log(`watching ${board.agentName}'s queue; command: ${command.join(" ")}`);
200
288
  while (!state.stopped) {