@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 +117 -3
- package/dist/cli.js +57 -13
- package/dist/engines.js +126 -0
- package/dist/repo.js +3 -1
- package/dist/service.js +29 -4
- package/dist/watch.js +115 -27
- package/dist/worker.js +1119 -0
- package/engine/prompt.md +58 -0
- package/package.json +2 -1
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
|
-
|
|
131
|
-
|
|
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
|
|
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
|
|
347
|
-
|
|
348
|
-
|
|
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;
|
package/dist/engines.js
ADDED
|
@@ -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
|
|
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
|
-
/**
|
|
136
|
-
|
|
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", {
|
|
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
|
|
170
|
-
const whenAwake =
|
|
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) {
|