@mergeline/agent 0.5.3 → 0.6.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 +117 -3
- package/dist/cli.js +64 -19
- package/dist/engines.js +126 -0
- package/dist/mcp.js +3 -2
- package/dist/repo.js +6 -3
- package/dist/service.js +29 -4
- package/dist/terminal.js +30 -0
- package/dist/watch.js +115 -27
- package/dist/worker.js +1098 -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,10 +28,13 @@ 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";
|
|
34
36
|
import { BoardError, TicketService } from "./service.js";
|
|
37
|
+
import { terminalJson, terminalLine, terminalText } from "./terminal.js";
|
|
35
38
|
const HELP = `board: a Mergeline board from the command line
|
|
36
39
|
|
|
37
40
|
Usage:
|
|
@@ -63,6 +66,15 @@ Usage:
|
|
|
63
66
|
after --max-runs (default 10), after 2 runs that changed
|
|
64
67
|
nothing or 3 failed runs in a row. --usage-from claude-json
|
|
65
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
|
|
66
78
|
board whoami check the connection and show the agent
|
|
67
79
|
board list tickets assigned to you that are not done
|
|
68
80
|
board claim take your next ticket (or {"ticket": null})
|
|
@@ -163,7 +175,7 @@ function runInit(args) {
|
|
|
163
175
|
dryRun,
|
|
164
176
|
noNpx: args.includes("--no-npx"),
|
|
165
177
|
});
|
|
166
|
-
const out = process.stdout;
|
|
178
|
+
const out = { write: (s) => process.stdout.write(terminalText(s)) };
|
|
167
179
|
out.write(`${dryRun ? "Would change" : "Agent kit"} in ${dir}:\n`);
|
|
168
180
|
for (const a of result.actions)
|
|
169
181
|
out.write(` ${a.kind.padEnd(9)} ${a.path}${a.note ? ` (${a.note})` : ""}\n`);
|
|
@@ -256,7 +268,7 @@ async function runStart(args) {
|
|
|
256
268
|
}
|
|
257
269
|
const b = new TicketService({ url: saved.url, key: saved.key });
|
|
258
270
|
await b.login();
|
|
259
|
-
process.stderr.write(`board: ${command[0]} as ${saved.name} on ${saved.url}${command[0] === "claude" ? "; type /pick to take a ticket" : ""}\n`);
|
|
271
|
+
process.stderr.write(terminalText(`board: ${command[0]} as ${saved.name} on ${saved.url}${command[0] === "claude" ? "; type /pick to take a ticket" : ""}\n`));
|
|
260
272
|
const child = spawn(command[0], command.slice(1), {
|
|
261
273
|
stdio: "inherit",
|
|
262
274
|
env: { ...process.env, BOARD_URL: saved.url, BOARD_AGENT_KEY: saved.key, BOARD_AGENT: saved.name },
|
|
@@ -264,7 +276,7 @@ async function runStart(args) {
|
|
|
264
276
|
const code = await new Promise((res) => {
|
|
265
277
|
child.on("exit", (c, signal) => res(c ?? (signal ? 1 : 0)));
|
|
266
278
|
child.on("error", (err) => {
|
|
267
|
-
process.stderr.write(`board: could not start ${command[0]}: ${err.message}\n`);
|
|
279
|
+
process.stderr.write(terminalText(`board: could not start ${command[0]}: ${err.message}\n`));
|
|
268
280
|
res(127);
|
|
269
281
|
});
|
|
270
282
|
});
|
|
@@ -320,10 +332,7 @@ async function main(argvIn) {
|
|
|
320
332
|
case "watch": {
|
|
321
333
|
const sep = rawArgs.indexOf("--");
|
|
322
334
|
const opts = sep < 0 ? rawArgs : rawArgs.slice(0, sep);
|
|
323
|
-
const
|
|
324
|
-
if (agentCommand.length === 0) {
|
|
325
|
-
throw new UsageError('board watch needs the agent command after --, e.g. board watch -- claude -p "/pick"');
|
|
326
|
-
}
|
|
335
|
+
const after = sep < 0 ? [] : rawArgs.slice(sep + 1);
|
|
327
336
|
const num = (flag, fallback) => {
|
|
328
337
|
const i = opts.indexOf(flag);
|
|
329
338
|
if (i < 0)
|
|
@@ -333,23 +342,59 @@ async function main(argvIn) {
|
|
|
333
342
|
throw new UsageError(`${flag} needs a whole number, 1 or more`);
|
|
334
343
|
return n;
|
|
335
344
|
};
|
|
336
|
-
const known = new Set(["--follow", "--interval", "--max-runs", "--usage-from"]);
|
|
337
|
-
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"];
|
|
338
347
|
const unknown = opts.find((a, i) => a.startsWith("--") && !known.has(a) && !valued.includes(opts[i - 1] ?? ""));
|
|
339
|
-
const ui = opts.indexOf("--usage-from");
|
|
340
|
-
const usageFrom = ui < 0 ? undefined : opts[ui + 1];
|
|
341
|
-
if (ui >= 0 && usageFrom !== "claude-json")
|
|
342
|
-
throw new UsageError("--usage-from supports claude-json (claude -p --output-format json)");
|
|
343
348
|
if (unknown)
|
|
344
349
|
throw new UsageError(`unknown option ${unknown}; run board help`);
|
|
345
|
-
const
|
|
346
|
-
|
|
347
|
-
|
|
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 = {
|
|
348
354
|
maxRuns: num("--max-runs", 10),
|
|
349
355
|
follow: opts.includes("--follow"),
|
|
350
356
|
intervalSec: num("--interval", 30),
|
|
351
357
|
lockFile: file.replace(/session-([^/\\]+)\.json$/, "watch-$1.lock"),
|
|
352
|
-
log: (line) => process.stderr.write(`board watch: ${line}\n`),
|
|
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,
|
|
353
398
|
usageFrom: usageFrom,
|
|
354
399
|
});
|
|
355
400
|
process.exitCode = code;
|
|
@@ -398,9 +443,9 @@ async function main(argvIn) {
|
|
|
398
443
|
}
|
|
399
444
|
main(process.argv.slice(2)).then((result) => {
|
|
400
445
|
if (result !== undefined)
|
|
401
|
-
process.stdout.write(
|
|
446
|
+
process.stdout.write(terminalJson(result, 2) + "\n");
|
|
402
447
|
}, (err) => {
|
|
403
448
|
const message = err instanceof BoardError || err instanceof UsageError || err instanceof Error ? err.message : String(err);
|
|
404
|
-
process.stderr.write(`board: ${message.split("\n")[0]}\n`);
|
|
449
|
+
process.stderr.write(`board: ${terminalText(message.split("\n")[0])}\n`);
|
|
405
450
|
process.exit(err instanceof UsageError ? 2 : 1);
|
|
406
451
|
});
|
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/mcp.js
CHANGED
|
@@ -10,6 +10,7 @@ import { z } from "zod";
|
|
|
10
10
|
import { PACKAGE_VERSION } from "./init.js";
|
|
11
11
|
import { agentCredentialsFromEnv } from "./pb.js";
|
|
12
12
|
import { BoardError, TicketService } from "./service.js";
|
|
13
|
+
import { terminalText } from "./terminal.js";
|
|
13
14
|
const ticketId = z.string().min(1).describe("Ticket id, as returned by claim");
|
|
14
15
|
const usage = z
|
|
15
16
|
.object({
|
|
@@ -127,14 +128,14 @@ export async function runMcpServer() {
|
|
|
127
128
|
// here may not get): serve anyway, so the agent sees why on its first
|
|
128
129
|
// tool call, and send nothing to any board.
|
|
129
130
|
const message = err instanceof Error ? err.message : String(err);
|
|
130
|
-
console.error(`board MCP: ${message}`);
|
|
131
|
+
console.error(terminalText(`board MCP: ${message}`));
|
|
131
132
|
await createServer(refusingBoard(message)).connect(new StdioServerTransport());
|
|
132
133
|
return;
|
|
133
134
|
}
|
|
134
135
|
// Log in up front so a bad config shows in the MCP logs right away. On
|
|
135
136
|
// failure keep serving: every tool call retries the login and returns the
|
|
136
137
|
// reason as a plain tool error.
|
|
137
|
-
await board.login().then(() => console.error(`board MCP: logged in as ${board.agentName}`), (err) => console.error(`board MCP: ${err instanceof Error ? err.message : String(err)}`));
|
|
138
|
+
await board.login().then(() => console.error(terminalText(`board MCP: logged in as ${board.agentName}`)), (err) => console.error(terminalText(`board MCP: ${err instanceof Error ? err.message : String(err)}`)));
|
|
138
139
|
await createServer(board).connect(new StdioServerTransport());
|
|
139
140
|
}
|
|
140
141
|
/** A stand-in for TicketService whose every call fails with message, before any request. */
|
package/dist/repo.js
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
// ../.wt/<ticket>). BOARD_URL, when set, wins over it.
|
|
12
12
|
import { existsSync, readFileSync } from "node:fs";
|
|
13
13
|
import { dirname, join } from "node:path";
|
|
14
|
+
import { terminalJson } from "./terminal.js";
|
|
14
15
|
export const REPO_FILE = ".mergeline.json";
|
|
15
16
|
/**
|
|
16
17
|
* A board address in one form, so the same board is the same string wherever
|
|
@@ -23,10 +24,10 @@ export function normalizeBoardUrl(raw) {
|
|
|
23
24
|
url = new URL(raw.trim());
|
|
24
25
|
}
|
|
25
26
|
catch {
|
|
26
|
-
throw new Error(
|
|
27
|
+
throw new Error(`${terminalJson(raw)} is not a board address; give it as shown on the board, e.g. https://acme.mergeline.app`);
|
|
27
28
|
}
|
|
28
29
|
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
|
29
|
-
throw new Error(
|
|
30
|
+
throw new Error(`${terminalJson(raw)} is not a board address: it must start with https:// (or http://)`);
|
|
30
31
|
}
|
|
31
32
|
return (url.origin + url.pathname).replace(/\/+$/, "");
|
|
32
33
|
}
|
|
@@ -49,7 +50,7 @@ export function readRepoFile(file) {
|
|
|
49
50
|
catch {
|
|
50
51
|
throw new Error(`${file} is not valid JSON; run board init --url <board> to write it again`);
|
|
51
52
|
}
|
|
52
|
-
const { board, kit } = (data ?? {});
|
|
53
|
+
const { board, kit, test } = (data ?? {});
|
|
53
54
|
const out = {};
|
|
54
55
|
if (board !== undefined) {
|
|
55
56
|
if (typeof board !== "string" || !board)
|
|
@@ -63,6 +64,8 @@ export function readRepoFile(file) {
|
|
|
63
64
|
}
|
|
64
65
|
if (typeof kit === "number" && Number.isInteger(kit))
|
|
65
66
|
out.kit = kit;
|
|
67
|
+
if (typeof test === "string" && test.trim())
|
|
68
|
+
out.test = test.trim();
|
|
66
69
|
return out;
|
|
67
70
|
}
|
|
68
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/terminal.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// Text that others chose (a repository's .mergeline.json, a board's ticket
|
|
2
|
+
// titles, event text and error messages) must not drive the developer's
|
|
3
|
+
// terminal: an escape sequence in it can erase or rewrite the lines around
|
|
4
|
+
// it, set the window title, add hyperlinks or write the clipboard. Whatever
|
|
5
|
+
// the CLI, `board watch` and the MCP server write to stdout or stderr goes
|
|
6
|
+
// through one of these; what tools return to the model does not.
|
|
7
|
+
/**
|
|
8
|
+
* The one list. DEL, C1 (U+009B is a CSI on its own) and the bidirectional
|
|
9
|
+
* controls (U+061C, U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069):
|
|
10
|
+
* JSON.stringify leaves them raw.
|
|
11
|
+
*/
|
|
12
|
+
const BEYOND_JSON_CLASS = "\\u007f-\\u009f\\u061c\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069";
|
|
13
|
+
/** C0 but LF and TAB. */
|
|
14
|
+
const C0_CLASS = "\\u0000-\\u0008\\u000b-\\u001f";
|
|
15
|
+
const BEYOND_JSON = new RegExp(`[${BEYOND_JSON_CLASS}]`, "g");
|
|
16
|
+
const UNSAFE = new RegExp(`[${C0_CLASS}${BEYOND_JSON_CLASS}]`, "g");
|
|
17
|
+
const UNSAFE_OR_LF = new RegExp(`[\\n${C0_CLASS}${BEYOND_JSON_CLASS}]`, "g");
|
|
18
|
+
const escape = (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`;
|
|
19
|
+
/** Text safe for a terminal: every control character but LF and TAB written as a visible \uXXXX. */
|
|
20
|
+
export function terminalText(text) {
|
|
21
|
+
return text.replace(UNSAFE, escape);
|
|
22
|
+
}
|
|
23
|
+
/** One line safe for a terminal: terminalText, with LF also written as \u000a so the text cannot start a line of its own. */
|
|
24
|
+
export function terminalLine(text) {
|
|
25
|
+
return text.replace(UNSAFE_OR_LF, escape);
|
|
26
|
+
}
|
|
27
|
+
/** JSON (still valid) safe for a terminal: JSON.stringify, with DEL, C1 and the bidirectional controls as \u escapes. */
|
|
28
|
+
export function terminalJson(value, indent) {
|
|
29
|
+
return JSON.stringify(value, null, indent).replace(BEYOND_JSON, escape);
|
|
30
|
+
}
|