@mergeline/agent 0.4.0 → 0.4.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
@@ -22,7 +22,10 @@ npx -y @mergeline/agent start fe-1 # eve
22
22
 
23
23
  `init --url` writes the board's address into `.mergeline.json` (no
24
24
  secrets; commit it), so in that repository, and in the agents' worktrees of
25
- it, the commands below use that board. `login` checks the key with the
25
+ it, the commands below use that board. The file also holds the kit's
26
+ version, which every claim sends with the package's: when the board expects
27
+ a newer kit, the claim's answer says to run
28
+ `npx -y @mergeline/agent@latest init --claude` again. `login` checks the key with the
26
29
  board and saves it in `~/.config/mergeline/credentials.json` (readable only
27
30
  by you, outside any repository), per board and agent: `fe-1` on two boards
28
31
  is two saved keys. In a repository with `.mergeline.json`, `--url` can be
package/dist/cli.js CHANGED
@@ -175,7 +175,7 @@ function runInit(args) {
175
175
  ` board login <agent name> ${result.board ? "" : "--url <board address> "}--key <key>` +
176
176
  (result.board ? ` (the board: ${result.board}, from ${REPO_FILE})` : "") + "\n" +
177
177
  "and start each session with: board start <agent name>" + (args.includes("--codex") ? " -- codex" : "") + "\n" +
178
- "Commit AGENTS.md" + (args.includes("--claude") ? ", CLAUDE.md, .claude/, .mcp.json" : "") + (result.board ? `, ${REPO_FILE}` : "") +
178
+ "Commit AGENTS.md" + (args.includes("--claude") ? ", CLAUDE.md, .claude/, .mcp.json" : "") + `, ${REPO_FILE}` +
179
179
  " so every checkout has the kit; the key is not in any of them.\n");
180
180
  if (args.includes("--claude")) {
181
181
  out.write("Claude Code applies .claude/settings.json (the board's permissions) only in a trusted folder:\n" +
package/dist/init.js CHANGED
@@ -13,8 +13,11 @@
13
13
  // The permissions also allow the repository's own package manager (from its
14
14
  // lockfile) to install and to run its test, lint and typecheck scripts, so an
15
15
  // unattended agent does not stop at `pnpm install` in a new worktree.
16
- // - --url <board> writes the board's address into .mergeline.json (repo.ts),
17
- // so the board commands in this repository pick that board's saved key.
16
+ // - .mergeline.json (repo.ts) gets the kit's version and, with --url, the
17
+ // board's address, so the board commands in this repository pick that
18
+ // board's saved key. The version is also in the section's start marker and
19
+ // in each kit file's marker line; init finds both by their prefix, so files
20
+ // from an older kit are still updated.
18
21
  // - --codex writes the prompts into $CODEX_HOME/prompts (default
19
22
  // ~/.codex/prompts) and prints the MCP snippet for ~/.codex/config.toml,
20
23
  // which init does not edit. The snippet names the agent; its key stays in
@@ -23,15 +26,26 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
23
26
  import { homedir } from "node:os";
24
27
  import { dirname, join, relative } from "node:path";
25
28
  import { fileURLToPath } from "node:url";
26
- import { readRepoBoard, REPO_FILE } from "./repo.js";
29
+ import { readRepoFile, REPO_FILE } from "./repo.js";
27
30
  const KIT = fileURLToPath(new URL("../kit/", import.meta.url));
31
+ const PACKAGE = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
28
32
  /** This package's npm name, for the npx commands init writes (one place to rename it). */
29
- export const PACKAGE_NAME = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).name;
30
- const START = "<!-- mergeline:start (managed by `board init`; edit outside these markers) -->";
31
- /** Markers are found by these prefixes, so an edited marker line still counts. */
33
+ export const PACKAGE_NAME = PACKAGE.name;
34
+ /** Sent with every claim as `client`. */
35
+ export const PACKAGE_VERSION = PACKAGE.version;
36
+ /**
37
+ * The version of agent/kit: raise it with every change to the kit's files
38
+ * (kit-check fails until you do). Kit 1 is everything up to package 0.4.0,
39
+ * which wrote no version. The board says when a claim's kit is older than it
40
+ * expects (KIT_MIN in pocketbase/pb_hooks/board_lib.js).
41
+ */
42
+ export const KIT_VERSION = 2;
43
+ const START = `<!-- mergeline:start (kit ${KIT_VERSION}; managed by \`board init\`; edit outside these markers) -->`;
44
+ /** Markers are found by these prefixes, so an edited marker line or an older kit's still counts. */
32
45
  const START_PREFIX = "<!-- mergeline:start";
33
46
  const END = "<!-- mergeline:end -->";
34
- const MANAGED = "<!-- mergeline: written by `board init`; init updates this file while this line is here -->";
47
+ const MANAGED = `<!-- mergeline: written by \`board init\` (kit ${KIT_VERSION}); init updates this file while this line is here -->`;
48
+ const MANAGED_PREFIX = "<!-- mergeline: written by `board init`";
35
49
  function kit(name) {
36
50
  return readFileSync(join(KIT, name), "utf8").replace(/\s+$/, "") + "\n";
37
51
  }
@@ -109,7 +123,7 @@ export function init(opts) {
109
123
  return record(path, "create");
110
124
  }
111
125
  const current = readFileSync(path, "utf8");
112
- if (!current.includes(MANAGED))
126
+ if (!current.includes(MANAGED_PREFIX))
113
127
  return record(path, "skip", "a file of this name exists and was not written by board init");
114
128
  if (current === content)
115
129
  return record(path, "unchanged");
@@ -138,32 +152,36 @@ export function init(opts) {
138
152
  record(path, kind);
139
153
  }
140
154
  const promptFile = (name) => `---\ndescription: ${COMMANDS[name]}\n---\n\n${MANAGED}\n\n${kit(`${name}.md`)}`;
141
- /** .mergeline.json: the board's address, written only with --url. */
142
- function boardFile(path, url) {
143
- let current;
144
- try {
145
- current = existsSync(path) ? readRepoBoard(path) : undefined;
146
- }
147
- catch {
148
- current = undefined;
155
+ /** .mergeline.json: the kit's version and the board's address (from --url, else the one there). */
156
+ function repoFile(path, url) {
157
+ let current = {};
158
+ if (existsSync(path)) {
159
+ try {
160
+ current = readRepoFile(path);
161
+ }
162
+ catch (err) {
163
+ if (!url) {
164
+ record(path, "skip", `${err instanceof Error ? err.message : String(err)}`);
165
+ return undefined;
166
+ }
167
+ }
149
168
  }
150
- if (!url)
151
- return current;
152
- const content = JSON.stringify({ board: url }, null, 2) + "\n";
169
+ const board = url ?? current.board;
170
+ const content = JSON.stringify({ ...(board ? { board } : {}), kit: KIT_VERSION }, null, 2) + "\n";
153
171
  if (!existsSync(path)) {
154
172
  write(path, content, "create");
155
173
  record(path, "create");
156
174
  }
157
- else if (current === url && readFileSync(path, "utf8") === content) {
175
+ else if (readFileSync(path, "utf8") === content) {
158
176
  record(path, "unchanged");
159
177
  }
160
178
  else {
161
179
  write(path, content, "update");
162
- record(path, "update", current && current !== url ? `board ${current} -> ${url}` : undefined);
180
+ record(path, "update", current.board && url && current.board !== url ? `board ${current.board} -> ${url}` : undefined);
163
181
  }
164
- return url;
182
+ return board;
165
183
  }
166
- const board = boardFile(join(opts.dir, REPO_FILE), opts.url);
184
+ const board = repoFile(join(opts.dir, REPO_FILE), opts.url);
167
185
  let project = [];
168
186
  const rules = kit("rules.md");
169
187
  section(join(opts.dir, "AGENTS.md"), rules);
package/dist/mcp.js CHANGED
@@ -6,6 +6,7 @@
6
6
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
7
7
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
8
8
  import { z } from "zod";
9
+ import { PACKAGE_VERSION } from "./init.js";
9
10
  import { agentCredentialsFromEnv } from "./pb.js";
10
11
  import { BoardError, TicketService } from "./service.js";
11
12
  const ticketId = z.string().min(1).describe("Ticket id, as returned by claim");
@@ -32,7 +33,7 @@ async function run(fn) {
32
33
  }
33
34
  }
34
35
  export function createServer(board) {
35
- const server = new McpServer({ name: "board", version: "0.1.0" });
36
+ const server = new McpServer({ name: "board", version: PACKAGE_VERSION });
36
37
  server.registerTool("list_mine", {
37
38
  title: "List my tickets",
38
39
  description: "List the tickets assigned to you that are not done, with status, priority and block. " +
@@ -48,7 +49,7 @@ export function createServer(board) {
48
49
  "The ticket comes with spec_path, branch, answer and notes: the spec on main plus answer and " +
49
50
  "notes are your only requirements. Claiming starts a lease (claimed_until); keep it alive with heartbeat. " +
50
51
  "If it fails because another session of yours holds your ticket, say so and stop: do not retry and do not " +
51
- "start other work.",
52
+ "start other work. If the answer has kit_outdated, tell the human what it says and go on with the ticket.",
52
53
  }, () => run(() => board.claim()));
53
54
  server.registerTool("heartbeat", {
54
55
  title: "Extend lease",
package/dist/repo.js CHANGED
@@ -1,8 +1,10 @@
1
- // Which board a repository works with: `board init --url <board>` writes the
2
- // board's address into .mergeline.json at the repository's root (no secrets;
3
- // committed), so `board start <name>` there picks that board's saved key.
1
+ // Which board a repository works with and which kit it has: `board init`
2
+ // writes .mergeline.json at the repository's root (no secrets; committed),
3
+ // with the board's address when given --url, so `board start <name>` there
4
+ // picks that board's saved key, and the kit's version, which claims carry so
5
+ // the board can say when the kit is old.
4
6
  //
5
- // { "board": "https://acme.mergeline.app" }
7
+ // { "board": "https://acme.mergeline.app", "kit": 2 }
6
8
  //
7
9
  // The file is looked up from the current folder upwards, up to the root of
8
10
  // the git checkout (a folder with .git, which is a file in a worktree such as
@@ -38,8 +40,8 @@ export function findRepoFile(dir) {
38
40
  return null;
39
41
  }
40
42
  }
41
- /** The board a .mergeline.json names; an error that says which file when it is broken. */
42
- export function readRepoBoard(file) {
43
+ /** A .mergeline.json's contents; an error that says which file when it is broken. */
44
+ export function readRepoFile(file) {
43
45
  let data;
44
46
  try {
45
47
  data = JSON.parse(readFileSync(file, "utf8"));
@@ -47,14 +49,30 @@ export function readRepoBoard(file) {
47
49
  catch {
48
50
  throw new Error(`${file} is not valid JSON; run board init --url <board> to write it again`);
49
51
  }
50
- const board = data?.board;
51
- if (typeof board !== "string" || !board)
52
- throw new Error(`${file} has no "board" address; run board init --url <board>`);
52
+ const { board, kit } = (data ?? {});
53
+ const out = {};
54
+ if (board !== undefined) {
55
+ if (typeof board !== "string" || !board)
56
+ throw new Error(`${file} has no "board" address; run board init --url <board>`);
57
+ try {
58
+ out.board = normalizeBoardUrl(board);
59
+ }
60
+ catch (err) {
61
+ throw new Error(`${file}: ${err instanceof Error ? err.message : String(err)}`);
62
+ }
63
+ }
64
+ if (typeof kit === "number" && Number.isInteger(kit))
65
+ out.kit = kit;
66
+ return out;
67
+ }
68
+ /** The kit version of the repository around cwd, or undefined (no file, no version, or a broken file). */
69
+ export function repoKit(cwd = process.cwd()) {
70
+ const file = findRepoFile(cwd);
53
71
  try {
54
- return normalizeBoardUrl(board);
72
+ return file ? readRepoFile(file).kit : undefined;
55
73
  }
56
- catch (err) {
57
- throw new Error(`${file}: ${err instanceof Error ? err.message : String(err)}`);
74
+ catch {
75
+ return undefined;
58
76
  }
59
77
  }
60
78
  /** The board in use here: BOARD_URL, else the repository's .mergeline.json, else null. */
@@ -63,5 +81,6 @@ export function boardInContext(env = process.env, cwd = process.cwd()) {
63
81
  if (fromEnv)
64
82
  return { url: normalizeBoardUrl(fromEnv), from: "BOARD_URL" };
65
83
  const file = findRepoFile(cwd);
66
- return file ? { url: readRepoBoard(file), from: file } : null;
84
+ const board = file ? readRepoFile(file).board : undefined;
85
+ return board ? { url: board, from: file } : null;
67
86
  }
package/dist/service.js CHANGED
@@ -5,6 +5,8 @@
5
5
  // reimplementing this file only.
6
6
  import { randomUUID } from "node:crypto";
7
7
  import PocketBase, { ClientResponseError } from "pocketbase";
8
+ import { PACKAGE_VERSION } from "./init.js";
9
+ import { repoKit } from "./repo.js";
8
10
  /** An error whose message is safe to show to an agent or a human as is. */
9
11
  export class BoardError extends Error {
10
12
  status;
@@ -130,8 +132,10 @@ export class TicketService {
130
132
  return records;
131
133
  });
132
134
  }
135
+ /** Carries this package's version and the repository's kit version (repo.ts), so the board can say when the kit is old. */
133
136
  claim() {
134
- return this.post("claim", {});
137
+ const kit = repoKit();
138
+ return this.post("claim", { client: PACKAGE_VERSION, ...(kit === undefined ? {} : { kit }) });
135
139
  }
136
140
  heartbeat(ticketId, note) {
137
141
  return this.post("heartbeat", { ticket_id: ticketId, note: note ?? "" });
package/kit/done.md CHANGED
@@ -6,14 +6,17 @@ the `board` command of the same name (`submit_for_review` is `board submit`).
6
6
  `npm run lint`; use what the project has). If they fail, fix them. If you
7
7
  cannot, call `log_event` kind `warn` with what fails, then `ask_human`,
8
8
  and stop.
9
- 2. Commit with a clear message and push the branch:
9
+ 2. Call `heartbeat` before you push. If it says another session holds the
10
+ ticket, stop at once: do not commit, push or open a PR. If it says to
11
+ claim again, stop and claim.
12
+ 3. Commit with a clear message and push the branch:
10
13
  `git push -u origin <branch>`.
11
- 3. Open a PR against `main` with `gh pr create`. Title: the ticket title.
14
+ 4. Open a PR against `main` with `gh pr create`. Title: the ticket title.
12
15
  The body names the ticket id, the spec path and the spec commit
13
16
  (`record_spec`). If a PR for the branch already exists
14
17
  (`gh pr view <branch>`), the push updates it; use its URL.
15
- 4. Call `heartbeat`, then `submit_for_review` with the PR URL and a 2 to 4
16
- line summary of what changed. If your tool tells you what this work cost
17
- (tokens, cost), pass it as `usage`; otherwise leave it out.
18
- 5. Do not mark the ticket done and do not merge the PR. A human does that.
18
+ 5. Call `submit_for_review` with the PR URL and a 2 to 4 line summary of
19
+ what changed. If your tool tells you what this work cost (tokens, cost),
20
+ pass it as `usage`; otherwise leave it out.
21
+ 6. Do not mark the ticket done and do not merge the PR. A human does that.
19
22
  Stop here.
package/kit/rules.md CHANGED
@@ -27,3 +27,5 @@ the done instructions: `/pick` and `/done` in Claude Code,
27
27
  at once: no commit, no push, no PR.
28
28
  - If a board tool says the board is paused, stop and tell the human: it
29
29
  wakes when a person opens it. Do not retry in a loop.
30
+ - If `claim` answers with `kit_outdated`, tell the human what it says once
31
+ and go on with the ticket.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mergeline/agent",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "The agent's side of a Mergeline board: an MCP server and the `board` CLI. Works with any agent tool that runs MCP servers or shell commands.",
5
5
  "license": "MIT",
6
6
  "author": "frontender-ua",