agentlane 0.5.1 → 0.6.1-rc.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/CHANGELOG.md +58 -0
- package/README.md +70 -74
- package/dist/agents/host-timeouts.js +58 -0
- package/dist/agents/init.js +31 -19
- package/dist/agents/launcher.js +3 -1
- package/dist/agents/toml.js +34 -20
- package/dist/agents/wiring-check.js +12 -3
- package/dist/agents/wiring.js +39 -4
- package/dist/cli.js +3 -1
- package/dist/devices/simctl.js +27 -6
- package/dist/driver/client.js +39 -11
- package/dist/driver/engine.js +7 -1
- package/dist/driver/install.js +80 -20
- package/dist/driver/maestro-child.js +11 -3
- package/dist/driver/session.js +1 -1
- package/dist/driver/supervisor.js +48 -3
- package/dist/hooks/run.js +39 -14
- package/dist/plugin/aims.js +304 -6
- package/dist/plugin/guard.js +28 -2
- package/dist/plugin/hook-cli.js +11 -3
- package/dist/processes.js +43 -0
- package/dist/project/config.js +42 -4
- package/dist/project/schema.js +44 -0
- package/dist/registry/owner.js +10 -9
- package/dist/registry/parks.js +8 -2
- package/dist/registry/registry.js +183 -35
- package/dist/registry/resources.js +46 -7
- package/dist/registry/shared.js +384 -0
- package/dist/registry/status.js +10 -0
- package/dist/registry/store.js +98 -7
- package/dist/registry-cli.js +45 -1
- package/dist/services/system.js +4 -1
- package/dist/up/doctor.js +42 -1
- package/dist/up/exec.js +107 -8
- package/dist/up/lane-files.js +13 -0
- package/dist/up/lane-services.js +10 -0
- package/dist/up/maestro-env.js +6 -2
- package/dist/up/park.js +5 -3
- package/dist/up/preflight.js +8 -4
- package/dist/up/resources.js +104 -21
- package/dist/up/restart.js +21 -6
- package/dist/up/shared.js +321 -0
- package/dist/up/sweep.js +31 -6
- package/dist/up/up.js +76 -14
- package/dist/up/waker.js +9 -5
- package/dist/up-cli.js +35 -11
- package/package.json +8 -2
- package/schema/agentlane.schema.json +65 -0
- package/skills/create-verification-skill/SKILL.md +9 -4
- package/skills/dev-loop/SKILL.md +9 -3
- package/skills/setup/SKILL.md +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,64 @@
|
|
|
2
2
|
|
|
3
3
|
Newest first.
|
|
4
4
|
|
|
5
|
+
## 0.6.1
|
|
6
|
+
|
|
7
|
+
The first look or screenshot no longer fails when the XCTest runner takes over a minute to start, and a simctl timeout and a failed Maestro download now say what happened.
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- **The first look or screenshot on a fresh iOS driver waits for the XCTest runner.** That call also waits for Maestro to start its runner on the simulator, which Maestro allows 120 s for, but the driver cut it at 60 s and gave up after one try. Where the start takes longer, as it can on GitHub's macOS runners, `look` and `screenshot` failed with `Maestro's session failed (timeout)`, and `up` reported `driver: not started`. On a simulator, the first call on each Maestro now gets 120 s on top of its own 60 s, and the driver sets `MAESTRO_DRIVER_STARTUP_TIMEOUT` so Maestro waits the same 120 s. Calls after the runner has answered keep 60 s. A first read or screenshot that still times out, or that Maestro answers with `iOS driver not ready in time`, restarts Maestro and is tried once more. That error no longer tells you to raise `MAESTRO_DRIVER_STARTUP_TIMEOUT`, which the driver sets itself. It now says the next call starts a fresh runner.
|
|
12
|
+
- **The CLI and the MCP server wait longer on a simulator.** They wait up to 10 minutes for a look or a screenshot and 28 for a run, which covers a first call the driver tries twice. Emulators keep Maestro's own startup time and the earlier limits.
|
|
13
|
+
- **A session failure says whether the driver tried again.** A call tried once read `failed again after a restart`. It now reads `Maestro's session failed (timeout): ...`, and a call tried twice reads `... and failed again when the driver tried once more: ...`.
|
|
14
|
+
- **A simctl command that runs out of time says so.** `up`'s preflight read `simulator runtime: xcrun simctl list -j runtimes failed: ` with nothing after it, and told you to install a runtime that was installed. It now reads `xcrun simctl list -j runtimes didn't finish within 180 s`, with a fix that says to run the listing by hand. Listing the runtimes gets 180 s instead of 60. A simctl command that fails without writing to stderr now names its exit status or signal.
|
|
15
|
+
- **Agents no longer stop agentlane's MCP calls before agentlane does.** Codex stops an MCP call after 60 s, GitHub Copilot after 30 s, Antigravity after 3 minutes and Gemini CLI after 10, while a first look on a fresh iOS simulator can take minutes, a run up to 28 minutes, and the same call may first wake a parked lane or install Maestro. `init` now sets a 60-minute limit on agentlane's server for each of them: `tool_timeout_sec` in `.codex/config.toml`, `timeout` in `.mcp.json` and `.gemini/settings.json`, and `timeoutSeconds` in `.agents/mcp_config.json`. That is enough for a call that wakes a parked lane, installs Maestro and runs the longest flow, and the agent stops a call that waits longer. It raises a shorter value and keeps a longer one, and in Codex's `[mcp_servers.agentlane]` table it now keeps the other keys you set. The Codex and Gemini CLI plugins carry the same limit, and the Cursor plugin gets its own MCP file without Codex's key. `doctor` warns about an entry with no limit or a shorter one, naming the file, the key and the value. Run `init` again in each project to set it. Cursor's CLI stops an MCP call after 60 s and has no setting for it.
|
|
16
|
+
- **A failed Maestro download is an error `up` reports.** When `up` downloaded Maestro for a sign-in hook and the download couldn't connect, it crashed with `TypeError: fetch failed` and a stack trace. A download that can't connect is now tried once more, and a failed one reads `downloading Maestro <version> from <url> failed: <reason>`, with a fix. In the sign-in step, `up` exits as it does for any failed step. In `up`'s driver step, as before, it prints `driver: not started (...)` and carries on.
|
|
17
|
+
- **`exec` ends its command if the process that ran it, or any process above it, exits, so `npx agentlane exec` ends with the agent's shell.** `exec` watched only its parent. Under `npx` that parent is npm, which keeps running when the shell above it is killed, so the command ran on. `exec` now records the pid, parent pid and start time of each process above it as it starts. Once a second it asks whether each still exists, which starts no process. Every 10 seconds it also reads their start times and parent pids with one `ps`. A process whose start time and parent pid have both changed counts as replaced, which catches a pid the system gave to a new process and lets a clock step pass. Under Codex, the shared app-server daemon and the processes above it don't count, since the daemon outlives the Codex window that started it.
|
|
18
|
+
|
|
19
|
+
## 0.6.0
|
|
20
|
+
|
|
21
|
+
The server a project's lane databases live in can now be declared under `shared` in `agentlane.json`. It runs while a lane needs it and stops 5 minutes after the last one parks or ends, with its data kept. `up --no-app` gives tests a lane with the project's data and nothing else. The guard denies a `docker` or `podman` command that would leave a container running after the agent, and `exec` stops its command once the process that ran it is gone. This version runs beside 0.5.x on the same Mac; "Sharing a Mac with 0.5.x" lists what 0.5.x does differently.
|
|
22
|
+
|
|
23
|
+
### Moving from 0.5.x
|
|
24
|
+
|
|
25
|
+
1. **Run `init` again in each project, and commit what it changes.** `node_modules/.bin/agentlane init`, with the agents the project uses, rewrites the guard hooks so they start the toolkit for commands that name `docker` or `podman` too. Until then the container guard doesn't run in that agent, and `doctor` warns that the hooks are stale. Codex asks you to trust the changed hooks again with `/hooks`. The Claude Code plugin's hooks update with the plugin.
|
|
26
|
+
2. **Declare the database server under `shared`.** Give it a `start` that starts the server and exits, a `stop` that stops it and keeps its data, and a `ready` that exits 0 when it answers. `start` and `stop` must each cope with running twice and with finding the server already in the state they set. The docs' new page, A server the lanes share, has a Docker Postgres to copy. A server you started by hand is found running at the first `up` and kept, and from then on agentlane stops it once no lane needs it.
|
|
27
|
+
3. **A project that starts its server in a precondition**, such as one that runs `just local-db`: move the command into the shared service's `start`, and leave the precondition to check state only, such as `docker info >/dev/null 2>&1` with "start Docker Desktop" as its fix, or remove it. A precondition never starts a server: it runs before every `up`, and nothing stops what it starts.
|
|
28
|
+
4. **A project that starts its server in a resource's `create`**, such as a `scripts/lane/db.sh` that runs the container with `--restart unless-stopped` and whose teardown starts the container again to drop the lane's database: take the server start out of both `create` and `teardown`, so they only create and drop the lane's database, and put it in the shared service's `start`. agentlane starts the shared service before each `create` and each teardown that needs it.
|
|
29
|
+
5. **Drop restart policies.** A container with `--restart unless-stopped` or `restart: always` comes back whenever Docker starts, with no lane that needs it. Remove the policy from `start` and from compose files, and clear it on a container that already has one with `docker update --restart no <container>`.
|
|
30
|
+
6. **Name the server in `needs`.** Each resource and service that uses it lists it: `"needs": ["postgres"]`. A resource without `needs` doesn't start the server before its `create`, and a lane whose resources and services name none doesn't keep it up.
|
|
31
|
+
7. **Make test databases resources.** Each database the project's tests create, a test-only one included, becomes a resource that exports its URL (`TEST_DATABASE_URL`, say) and needs the server. Run the tests with `node_modules/.bin/agentlane up --no-app` and `node_modules/.bin/agentlane exec -- <test command>`, and change the run skill's test steps to match. The `setup` and `create-verification-skill` skills write configs this way.
|
|
32
|
+
8. **Move every branch that has a running lane.** A lane on a branch whose `agentlane.json` has no `shared` records no need for the server, even while it uses it. Once a lane on a moved branch finds the server running and keeps it, agentlane stops the server 5 minutes after that lane parks or ends, under the lane on the older branch. Before you rely on the stop, merge the `shared` config into every branch that has a lane, or run `release` in the lanes on the branches you don't move.
|
|
33
|
+
|
|
34
|
+
### Sharing a Mac with 0.5.x
|
|
35
|
+
|
|
36
|
+
- **One registry, still format 1.** This version adds the tables `shared_services` and `shared_needs`, and the columns `repository` and `needs` to `resources`, which 0.5.x doesn't read. 0.5.x keeps working on the file.
|
|
37
|
+
- **0.5.x refuses `shared` and `needs`.** Its schema allows neither, so a worktree still on 0.5.x fails validation on a config that uses them. Move a project to `shared` once its branches run this version.
|
|
38
|
+
- **0.5.x starts and stops no shared service.** A lane that 0.5.x parks or ends doesn't count as no longer needing its shared services. The next sweep of this version finds them running with nothing that needs them and stops them 5 minutes later.
|
|
39
|
+
- **Resources 0.5.x created record no needs.** Their teardown starts no shared service until an `up`, a wake or a `restart` of this version records what they need.
|
|
40
|
+
|
|
41
|
+
### New
|
|
42
|
+
|
|
43
|
+
- **Shared services.** `shared.<name>` in `agentlane.json` declares a server the lanes of one repository use together, with `start`, `stop`, `ready`, `cwd` and `timeoutSeconds` (180 by default). Resources and services name the ones they use in `needs`, and a name not declared under `shared` fails validation. There is one of each per repository, used by the lanes of all its worktrees. agentlane starts it in a new `shared` step of `up`, after the build preconditions and before the resources, when a parked lane wakes, in `restart`, and before a resource teardown that needs it. Two lanes coming up together start it once, and a server whose `ready` already passes is kept without running `start`. It stops 5 minutes after the last lane that needs it parks or ends. The stop runs from the sweep, which runs while any agentlane process runs: each MCP server checks every minute, and every command checks as it starts. With no agentlane process running, a due stop happens at the next agentlane command. A failed stop is tried again a minute later, and a failed start leaves the server counted as running, to stop under the same rule. A stop runs the commands, the folder, the `PATH` and the container tool's variables (`DOCKER_HOST`, `DOCKER_CONTEXT`, `COMPOSE_PROJECT_NAME` and the like) recorded at the last start, and runs in the shared service's log folder once that folder is gone. agentlane never removes a shared service.
|
|
44
|
+
- **`up --no-app`** brings up the project's data alone: the preflight checks that need no device, the preconditions that name no platform, setup, the shared services the resources need, the resources and doctor. It claims no device, browser or port, and builds and starts nothing. Commands run under `exec` with the resources' values. The lane parks and wakes like any other, and a later plain `up` in the folder adds the app to it with the same data. It is refused for a project with no resources, with `--platform`, `--no-cache`, `--refresh-cache` or `--timeout`, and in a folder whose lane already has the app. `restart` in a data-only lane is refused, exit 2, since the lane runs no service.
|
|
45
|
+
- **The guard denies containers that outlive their command.** `docker` and `podman` (and `docker-compose`, `podman-compose`) commands that leave a container running are denied: `run -d` in any of its spellings, `start`, `restart`, `compose up -d`, `--detach` or `--wait`, `compose start`, `compose restart`, `compose run -d`, `podman pod start` and `restart`, and `podman kube play` without `--down`. It reads them through `sh -c`, `npx`, `env`, `sudo`, `nohup`, `setsid`, full paths, split quotes and brace expansion. `run --rm`, foreground `compose up`, `exec`, `stop`, `rm`, `create` and the read-only commands pass, and so do host processes started with `nohup`, `&`, `setsid` or `disown`. The denial names `shared`, `up --no-app` and `exec` as the routes, and `AGENTLANE_ALLOW_CONTAINER=1` as the bypass, which agents use only when the user has asked, in that conversation, for a container outside lanes. agentlane doesn't track or stop such a container. The denial needs no registry, so it works when the state folder can't be read.
|
|
46
|
+
- **`doctor` checks shared services.** A `shared <name>` line for each shared service the lane needs runs its `ready` and fails with `up` as the fix. A data-only lane gets the config, wiring, lane, hook locale, resource and shared lines only.
|
|
47
|
+
- **`status` lists shared services** after the lanes: whether each runs, the lanes that need it, when it stops, and why its last start or stop failed, with its log. `lanes --json` has them in a top-level `shared` array.
|
|
48
|
+
|
|
49
|
+
### Changed
|
|
50
|
+
|
|
51
|
+
- **`exec` ends with the process that ran it.** When that process exits while the command runs, such as an agent's shell being killed, `exec` sends SIGTERM to the command and every process under it, SIGKILL 5 seconds later to whatever still runs, and exits 129. A command whose caller is gone before it starts never runs. While the caller lives, `exec` reads its parent pid once a second and nothing else changes: the command stays in the terminal's process group, gets Ctrl-C and reads the terminal. `nohup agentlane exec -- <server> &` followed by closing the shell now ends the server too.
|
|
52
|
+
- **`reap` exits 1 when a shared service's stop fails**, as it does on any other problem, and `reap --json` has a `shared` list of the services it stopped.
|
|
53
|
+
- **A teardown starts the shared services its resource needs first.** When that start fails, the teardown doesn't run and its record is kept with `teardown did not run, since shared service <name> did not start`, to be tried again by the next release or reap. One pass tries each failing shared service once.
|
|
54
|
+
- **`restart` starts any shared service the lane needs that isn't running**, before it stops the service, so a failed shared start leaves the running service alone.
|
|
55
|
+
- **The guard hooks start Node for commands that name `docker` or `podman`**, as they do for device and browser tools. `setsid` now passes through like `nohup`, so `setsid <device command>` gets the device check.
|
|
56
|
+
- **`up`'s claim step** reads `claimed lane <id>: no device, browser or port` for a lane that holds none, and a lane with no ports no longer ends the line with a stray comma.
|
|
57
|
+
- **The README, the docs home and the package description now open on the problem agentlane solves.**
|
|
58
|
+
|
|
59
|
+
### Fixed
|
|
60
|
+
|
|
61
|
+
- `agentlane schema` no longer opens the registry, so printing the schema leaves the state folder as it was.
|
|
62
|
+
|
|
5
63
|
## 0.5.1
|
|
6
64
|
|
|
7
65
|
Three checks no longer fail things that work, and the registry's lock holder names its caller.
|
package/README.md
CHANGED
|
@@ -5,15 +5,37 @@
|
|
|
5
5
|
</picture>
|
|
6
6
|
</p>
|
|
7
7
|
|
|
8
|
-
<p align="center"><strong>A running copy of your app for every AI coding agent.</strong></p>
|
|
9
|
-
|
|
10
8
|
<p align="center">
|
|
11
9
|
<a href="https://www.npmjs.com/package/agentlane"><img src="https://img.shields.io/npm/v/agentlane" alt="npm"></a>
|
|
12
|
-
<a href="
|
|
10
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
|
|
13
11
|
<a href="https://github.com/north-star-hq/agentlane/actions/workflows/ci.yml"><img src="https://github.com/north-star-hq/agentlane/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
14
12
|
</p>
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
<h3 align="center">Stop your coding agents fighting over ports, simulators and databases.</h3>
|
|
15
|
+
|
|
16
|
+
<p align="center">The fast, light way to run a copy of your app for every agent, with tools to see it and drive it, all at the same time.</p>
|
|
17
|
+
|
|
18
|
+
<p align="center"><strong>Reads the screen 50x faster than stock Maestro.</strong></p>
|
|
19
|
+
|
|
20
|
+
<picture>
|
|
21
|
+
<source media="(prefers-color-scheme: dark)" srcset="media/hero-dark.svg">
|
|
22
|
+
<img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, run agentlane up and get their own ports, dev server, database and a browser, iOS simulator or Android emulator. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its ports and device are released.">
|
|
23
|
+
</picture>
|
|
24
|
+
|
|
25
|
+
Whether you run several Claude Code sessions on one app, Codex and Cursor side by side, or agents testing iOS and Android at once, agentlane keeps them apart.
|
|
26
|
+
|
|
27
|
+
agentlane calls each copy a **lane**. Every lane has:
|
|
28
|
+
|
|
29
|
+
- Its own [ports, dev servers and database](https://north-star-hq.github.io/agentlane/docs/services.html), so no two agents start a server on the same port.
|
|
30
|
+
- Its own [iOS simulator, Android emulator or browser](https://north-star-hq.github.io/agentlane/docs/devices.html), which no other agent can touch.
|
|
31
|
+
- [`look`, `run` and `screenshot`](https://north-star-hq.github.io/agentlane/docs/drive.html), which see and drive the app the same way on all three.
|
|
32
|
+
- [`doctor`](https://north-star-hq.github.io/agentlane/docs/doctor.html), which checks that every server runs this worktree's code before the agent trusts it.
|
|
33
|
+
- [Videos, traces, logs and screenshots](https://north-star-hq.github.io/agentlane/docs/evidence.html) the agent keeps as proof.
|
|
34
|
+
- [Cleanup](https://north-star-hq.github.io/agentlane/docs/guard.html) when the agent is done: servers stop, databases go, and devices go back to the pool.
|
|
35
|
+
|
|
36
|
+
It works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity, on web apps, iOS and Android. It runs on your machine, with no account.
|
|
37
|
+
|
|
38
|
+
## Install
|
|
17
39
|
|
|
18
40
|
**1. In your project's root:**
|
|
19
41
|
|
|
@@ -27,96 +49,74 @@ npx agentlane init
|
|
|
27
49
|
Set this project up with agentlane.
|
|
28
50
|
```
|
|
29
51
|
|
|
30
|
-
|
|
52
|
+
Once setup reports ready, any agent in the project can take work like this:
|
|
31
53
|
|
|
32
|
-
|
|
33
|
-
<source media="(prefers-color-scheme: dark)" srcset="media/hero-dark.svg">
|
|
34
|
-
<img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, get their own lane from agentlane up: ports, dev server, database and a browser, iOS simulator or Android emulator. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its lane is released.">
|
|
35
|
-
</picture>
|
|
54
|
+
> Add a "clear completed" button to the list. Bring the app up on iOS and on the web, prove the button works with a Maestro flow and a Playwright test, and record a video of it.
|
|
36
55
|
|
|
37
|
-
##
|
|
56
|
+
## Speed
|
|
38
57
|
|
|
39
|
-
|
|
40
|
-
- **Web, iOS and Android in one tool.** [`look`, `run` and `screenshot`](https://north-star-hq.github.io/agentlane/docs/drive.html) work the same on a simulator, an emulator or a browser.
|
|
41
|
-
- **The whole environment, per agent.** [Ports, dev servers, a database, sign-in](https://north-star-hq.github.io/agentlane/docs/lanes.html), and a device or browser that no other agent touches.
|
|
42
|
-
- **Fast.** A warm lane reads the screen in about 0.15 s. See [Speed](#speed).
|
|
43
|
-
- **It checks the app before your agent trusts it.** [`doctor`](https://north-star-hq.github.io/agentlane/docs/doctor.html) confirms that every server runs this worktree's code, and names the fix when one doesn't.
|
|
44
|
-
- **Evidence you can open.** [Videos, traces, logs and screenshots](https://north-star-hq.github.io/agentlane/docs/evidence.html), plus the Maestro flows and Playwright tests your agent commits.
|
|
45
|
-
- **It cleans up.** When a session ends, [its lane is released](https://north-star-hq.github.io/agentlane/docs/guard.html): services stop, databases are torn down, and devices go back to the pool.
|
|
46
|
-
- **Local.** No account, no hosted service, [no telemetry of its own](#security-and-telemetry).
|
|
58
|
+
An agent reads its screen in **0.12 s**, where stock Maestro takes 6.5 s.
|
|
47
59
|
|
|
48
|
-
|
|
60
|
+
| | With agentlane | Without |
|
|
61
|
+
| ----------------------------- | --------------------------- | ---------------------- |
|
|
62
|
+
| Read the screen | 0.12 s | 6.5 s on stock Maestro |
|
|
63
|
+
| iOS build in a fresh worktree | 6.5 s from the shared cache | 91.5 s |
|
|
64
|
+
| Boot an Android emulator | Under 2 s from Quick Boot | 14.6 s cold |
|
|
49
65
|
|
|
50
|
-
|
|
51
|
-
| ---------------------------------- | ------------- | ------- |
|
|
52
|
-
| Read the screen with `look` | 0.15 s | 0.16 s |
|
|
53
|
-
| Take a screenshot | 0.16 s | 0.18 s |
|
|
54
|
-
| Click through `playwright-cli` | | 0.81 s |
|
|
66
|
+
[How we measured, and what makes it fast](https://north-star-hq.github.io/agentlane/docs/speed.html)
|
|
55
67
|
|
|
56
|
-
|
|
68
|
+
## The skills
|
|
57
69
|
|
|
58
|
-
-
|
|
59
|
-
- **A runner port per session.** Stock Maestro gives every iOS simulator's runner the same port, 22087, so with two simulators the second one started cold on every call: 6.5 s per screen read, against 0.12 s with our patch.
|
|
60
|
-
- **Quick taps.** On Android, `run --quick` skips Maestro's fixed 750 ms window settle and the screen reads after the tap.
|
|
61
|
-
- **A build cache your worktrees share.** The example app's iOS build took 91.5 s. A fresh worktree got its build from the cache in 6.5 s and reached the running app in 38.6 s.
|
|
62
|
-
- **A device pool.** Lanes reuse simulators and emulators instead of creating new ones, and emulators boot from their Quick Boot snapshot in 1.6 to 1.8 s, against 14.6 s for a cold boot.
|
|
70
|
+
[The skills](https://north-star-hq.github.io/agentlane/docs/skills.html) teach an agent the whole loop in your project, from setup to proof.
|
|
63
71
|
|
|
64
|
-
|
|
72
|
+
- **setup** finds how your project runs its apps, servers, data and sign-in, wires your agents, writes `agentlane.json`, and brings each app up until `doctor` reports ready. It asks you only what it can't find out.
|
|
73
|
+
- **dev-loop** is what an agent follows whenever it runs the app: one lane per session, `up`, `doctor` before trusting an instance, `release` when done, and what counts as proof.
|
|
74
|
+
- **drive** covers driving the lane's device or browser, turning what worked into a committed flow or test, and keeping evidence.
|
|
75
|
+
- **device** is drive's old name. It sends any run skill that still loads `device` to drive.
|
|
76
|
+
- **create-verification-skill** writes your project's run skill, with how to launch, check, drive and capture the app and a page per user-facing feature, and runs it end to end once before it is done.
|
|
77
|
+
- **maintain-verification-skill** keeps the run skill and its feature pages true as the app changes. It checks each page against the code, drives each feature, and opens at most one PR of corrections.
|
|
65
78
|
|
|
66
|
-
|
|
67
|
-
<summary>How these were measured</summary>
|
|
79
|
+
Claude Code can load the skills, the MCP server and the hooks as the agentlane plugin, and Codex, Cursor and Gemini CLI have plugins with the skills and the MCP server.
|
|
68
80
|
|
|
69
|
-
|
|
81
|
+
## agentlane and the tools you already use
|
|
70
82
|
|
|
71
|
-
|
|
72
|
-
- Browser column: the same bench on the example's web app, Playwright 1.64.0 with Chrome for Testing, a 0.2.0 development build.
|
|
73
|
-
- Port comparison: 16 reads per simulator on another app, stock Maestro 2.8.0 against an early build with the port patch.
|
|
74
|
-
- Build cache: single runs of 0.2.0 on the example app. Boot times: two boots each of a Pixel 8 emulator on Android 36.
|
|
83
|
+
agentlane is the same idea as a git worktree, for the running app. A worktree gives each agent its own copy of the code, and a lane gives it its own copy of the app, up and running.
|
|
75
84
|
|
|
76
|
-
|
|
85
|
+
### agentlane and Simlock
|
|
77
86
|
|
|
78
|
-
|
|
87
|
+
[Simlock](https://github.com/callstackincubator/simlock), from Callstack, leases iOS simulators, Android emulators and enrolled phones to coding agents that run in parallel. An agent asks for a device and gets one back, booted and checked, that no other agent touches until it lets go. A lane holds a simulator, emulator or browser for one agent too, and adds the rest of the running app around it: its ports, dev servers and database.
|
|
79
88
|
|
|
80
|
-
|
|
89
|
+
### agentlane and agent-device
|
|
81
90
|
|
|
82
|
-
|
|
91
|
+
[agent-device](https://github.com/callstack/agent-device), also from Callstack, lets coding agents control mobile, TV, desktop and web apps through a CLI, an MCP server and a Node.js API, on more platforms than agentlane covers. It also coordinates device access between agents in parallel worktrees. A lane starts the app's servers and database first, so what the agent drives already runs that worktree's code.
|
|
83
92
|
|
|
84
|
-
|
|
85
|
-
- [A database](https://north-star-hq.github.io/agentlane/docs/resources.html), or any resource you declare, created for the lane and torn down when it ends, after a crash too.
|
|
86
|
-
- Sign-in through your project's hook, so the app opens signed in.
|
|
87
|
-
- A [simulator, emulator](https://north-star-hq.github.io/agentlane/docs/devices.html) or [browser](https://north-star-hq.github.io/agentlane/docs/browsers.html) from a pool. When the pool is full, the request waits for a free device.
|
|
88
|
-
- `restart` changes one service's environment, such as a feature flag, without tearing the lane down.
|
|
93
|
+
### agentlane and portless
|
|
89
94
|
|
|
90
|
-
|
|
95
|
+
[portless](https://github.com/vercel-labs/portless), from Vercel Labs, gives each dev server a free port and a stable, named `.localhost` URL, and gives each linked worktree a subdomain of its own. A lane adds the database and the simulator, emulator or browser that go with those servers.
|
|
91
96
|
|
|
92
|
-
|
|
93
|
-
- `run` runs Maestro steps and prints what changed.
|
|
94
|
-
- In the browser, Playwright's `playwright-cli` (the default) or agent-browser, run through `agentlane exec`.
|
|
95
|
-
- [`record save`](https://north-star-hq.github.io/agentlane/docs/drive.html) turns the session's passing steps into a Maestro flow you can commit.
|
|
96
|
-
- `device` sets location, permissions, appearance, push notifications, the clipboard and links to open.
|
|
97
|
-
- Before launch, `up` sets the device's location, status bar and keyboard, so captures match from run to run.
|
|
97
|
+
### agentlane and worktrunk
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
[worktrunk](https://github.com/max-sixty/worktrunk) is a CLI for git worktrees, designed for running AI agents in parallel. You switch, list and remove worktrees by branch name, with hooks and shared build caches. A lane runs the app from each worktree, and the same session in a second worktree gets a second lane.
|
|
100
100
|
|
|
101
|
-
|
|
102
|
-
- [A hook](https://north-star-hq.github.io/agentlane/docs/guard.html) denies `simctl`, `adb`, `emulator`, `avdmanager`, `playwright-cli` and `agent-browser` commands aimed at another lane's device or browser.
|
|
103
|
-
- The next lane taken on the machine cleans up any lane whose session died, and `prune` deletes pool devices no lane holds.
|
|
101
|
+
### agentlane and Playwright
|
|
104
102
|
|
|
105
|
-
|
|
103
|
+
[Playwright](https://github.com/microsoft/playwright) drives Chromium, Firefox and WebKit with one API, and its `playwright-cli` is built for coding agents. agentlane drives the browser with it by default. A lane gives each agent its own Chrome for Testing, with a profile no other lane can read, and agentlane's hook stops one agent's commands from reaching another lane's browser.
|
|
106
104
|
|
|
107
|
-
|
|
105
|
+
### agentlane and Maestro
|
|
108
106
|
|
|
109
|
-
-
|
|
110
|
-
- **dev-loop** is what an agent follows whenever it runs the app: one lane per session, `up`, `doctor` before trusting an instance, `release` when done, and what counts as proof.
|
|
111
|
-
- **drive** covers driving the lane's device or browser, turning what worked into a committed flow or test, and keeping evidence.
|
|
112
|
-
- **create-verification-skill** writes your project's run skill, with how to launch, check, drive and capture the app and a page per user-facing feature, and runs it end to end once before it is done.
|
|
113
|
-
- **maintain-verification-skill** keeps the run skill and its feature pages true as the app changes. It checks each page against the code, drives each feature, and opens at most one PR of corrections.
|
|
107
|
+
[Maestro](https://github.com/mobile-dev-inc/Maestro) tests Android, iOS and web apps through YAML flows, and its MCP server lets coding agents drive a live device. agentlane drives every simulator and emulator with it and keeps a Maestro session warm between calls. Its patched Maestro gives each iOS simulator's runner a port of its own, so a second simulator doesn't start cold on every call.
|
|
114
108
|
|
|
115
|
-
|
|
109
|
+
### agentlane and Conductor
|
|
116
110
|
|
|
117
|
-
|
|
111
|
+
[Conductor](https://www.conductor.build/) runs Claude Code, Codex, Cursor and OpenCode in parallel, each task in its own workspace and branch, on your Mac or in Conductor Cloud's sandboxes. A setup script runs in each new workspace to install dependencies and prepare files, and each workspace gets its own range of ports for the app's servers. On your Mac, a lane adds a database and a simulator, emulator or browser to each workspace.
|
|
118
112
|
|
|
119
|
-
|
|
113
|
+
### agentlane and Paradev
|
|
114
|
+
|
|
115
|
+
[Paradev](https://github.com/ParadevAI/Paradev), formerly Superset, is an open-source desktop app for running CLI coding agents in parallel. Each task gets its own git worktree, branch and terminals, and a built-in browser previews each workspace's dev server. Setup and teardown scripts run as each workspace is created and deleted, to install its dependencies or to start its containers and remove them. A lane gives each agent an iOS simulator or Android emulator of its own as well.
|
|
116
|
+
|
|
117
|
+
### agentlane and your agent's own worktrees
|
|
118
|
+
|
|
119
|
+
Claude Code's `--worktree`, the Codex app's worktrees and Cursor's worktrees each give an agent its own checkout, so parallel edits don't collide. Codex and Cursor can also run setup scripts in every new one. A lane runs the app from that checkout, and `doctor` confirms that every server is running that worktree's code.
|
|
120
120
|
|
|
121
121
|
## Where it runs
|
|
122
122
|
|
|
@@ -149,18 +149,14 @@ agentlane is built on these projects, and we're grateful to their authors:
|
|
|
149
149
|
- [agent-browser](https://github.com/vercel-labs/agent-browser) is the other browser driver a lane can run.
|
|
150
150
|
- [pstack](https://github.com/cursor/plugins/tree/main/pstack), Lauren Tan's skills for Cursor, is where dev-loop and the two verification skills began. Parts of them are adapted from it under the MIT licence.
|
|
151
151
|
|
|
152
|
-
Other projects worth knowing, from people working on the same problem:
|
|
153
|
-
|
|
154
|
-
- [agent-device](https://github.com/callstack/agent-device) by Callstack: mobile automation for agents through a CLI, an MCP server and a Node.js API, on more platforms than agentlane covers.
|
|
155
|
-
- [MobileBuildMCP](https://github.com/getsentry/MobileBuildMCP) by Sentry, formerly XcodeBuildMCP: an MCP server and CLI with tools for agents working on iOS and macOS projects.
|
|
156
|
-
- The simulator and browser panes in Claude Code Desktop, and the built-in browser Codex uses in the ChatGPT desktop app, which put the running app next to the conversation.
|
|
157
|
-
|
|
158
152
|
The Android robot in the animation is Google's, used under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
|
|
159
153
|
|
|
160
154
|
## Documentation
|
|
161
155
|
|
|
162
156
|
The [docs site](https://north-star-hq.github.io/agentlane/) has per-agent setup, the config and CLI reference, platform requirements and troubleshooting, with an `llms.txt` for agents. [`examples/expo-app/`](examples/expo-app/) is the app agentlane is tested on, and [`CHANGELOG.md`](CHANGELOG.md) lists every release.
|
|
163
157
|
|
|
158
|
+
Star the repository if agentlane helps you. It helps other people find it.
|
|
159
|
+
|
|
164
160
|
## License
|
|
165
161
|
|
|
166
162
|
[MIT](LICENSE). The patched Maestro is Apache-2.0; [`maestro/`](maestro/) holds its patches and notice.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { TOOL } from "../name.js";
|
|
2
|
+
import { AGENT_NAMES } from "./detect.js";
|
|
3
|
+
/** Each host's per-server limit on one MCP call, where a project file can set it. Cursor has none. */
|
|
4
|
+
export const HOST_TIMEOUTS = {
|
|
5
|
+
// https://code.claude.com/docs/en/env-vars: MCP_TOOL_TIMEOUT defaults to 100000000 ms; MCP_TIMEOUT limits startup on its own
|
|
6
|
+
claude: { key: 'timeout', unit: 'ms', callSec: 100_000, connectSec: null, signed: false },
|
|
7
|
+
// https://learn.chatgpt.com/docs/extend/mcp: tool_timeout_sec defaults to 60; startup_timeout_sec limits startup on its own
|
|
8
|
+
codex: { key: 'tool_timeout_sec', unit: 's', callSec: 60, connectSec: null, signed: false },
|
|
9
|
+
// https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference: timeout defaults to 30000 ms and is also the connection budget, floored at 60000 ms
|
|
10
|
+
copilot: { key: 'timeout', unit: 'ms', callSec: 30, connectSec: 60, signed: false },
|
|
11
|
+
// https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md: timeout defaults to 600000 ms and also limits connecting and discovery
|
|
12
|
+
gemini: { key: 'timeout', unit: 'ms', callSec: 600, connectSec: 600, signed: false },
|
|
13
|
+
// https://antigravity.google/docs/mcp: a positive timeoutSeconds replaces both the 180 s call and the 300 s connect limit
|
|
14
|
+
antigravity: { key: 'timeoutSeconds', unit: 's', callSec: 180, connectSec: 300, signed: true },
|
|
15
|
+
};
|
|
16
|
+
export function hostTimeout(agent) {
|
|
17
|
+
const hosts = HOST_TIMEOUTS;
|
|
18
|
+
return hosts[agent];
|
|
19
|
+
}
|
|
20
|
+
/** The limit on one call agentlane writes for each host: long enough for a slow call that succeeds, short enough that a hung one gives the agent back. */
|
|
21
|
+
export const CALL_LIMIT_SEC = 60 * 60;
|
|
22
|
+
function inUnit(host, sec) {
|
|
23
|
+
return host.unit === 'ms' ? sec * 1000 : sec;
|
|
24
|
+
}
|
|
25
|
+
function neededSec(host) {
|
|
26
|
+
return Math.max(CALL_LIMIT_SEC, host.connectSec ?? 0);
|
|
27
|
+
}
|
|
28
|
+
/** The value agentlane writes for this host, in the host's unit. */
|
|
29
|
+
export function timeoutValue(host) {
|
|
30
|
+
return inUnit(host, neededSec(host));
|
|
31
|
+
}
|
|
32
|
+
function inEffect(host, value) {
|
|
33
|
+
return value === undefined || (host.signed && value === 0) ? inUnit(host, host.callSec) : value;
|
|
34
|
+
}
|
|
35
|
+
/** Whether the host, with this value of its key (undefined when unset), lets a call run as long as agentlane needs. */
|
|
36
|
+
export function coversCalls(host, value) {
|
|
37
|
+
const limit = inEffect(host, value);
|
|
38
|
+
if (typeof limit !== 'number' || !Number.isFinite(limit))
|
|
39
|
+
return false;
|
|
40
|
+
return limit >= timeoutValue(host) || (host.signed && limit < 0);
|
|
41
|
+
}
|
|
42
|
+
function duration(sec) {
|
|
43
|
+
return sec % 60 === 0 ? `${String(sec / 60)} min` : `${String(sec)} s`;
|
|
44
|
+
}
|
|
45
|
+
/** Why this host would stop a call sooner than agentlane needs, or null when it wouldn't. */
|
|
46
|
+
export function timeoutShortfall(agent, value) {
|
|
47
|
+
const host = hostTimeout(agent);
|
|
48
|
+
if (!host || coversCalls(host, value))
|
|
49
|
+
return null;
|
|
50
|
+
const needs = `${host.key} ${String(timeoutValue(host))} (${host.unit === 'ms' ? 'milliseconds' : 'seconds'}, ${duration(neededSec(host))})`;
|
|
51
|
+
const stops = `${AGENT_NAMES[agent]} stops a call after ${duration(host.callSec)}`;
|
|
52
|
+
const has = value === undefined
|
|
53
|
+
? `it has no ${host.key}, so ${stops}`
|
|
54
|
+
: inEffect(host, value) === value
|
|
55
|
+
? `its ${host.key} is ${JSON.stringify(value)}`
|
|
56
|
+
: `its ${host.key} is 0, which keeps the default, so ${stops}`;
|
|
57
|
+
return `${has}; ${TOOL} needs ${needs}`;
|
|
58
|
+
}
|
package/dist/agents/init.js
CHANGED
|
@@ -45,6 +45,10 @@ function refused(file, edits, reason) {
|
|
|
45
45
|
edits,
|
|
46
46
|
};
|
|
47
47
|
}
|
|
48
|
+
function shortfalls(found) {
|
|
49
|
+
const named = [...new Set(found.filter(reason => typeof reason === 'string'))];
|
|
50
|
+
return named.length > 0 ? named.join('; ') : null;
|
|
51
|
+
}
|
|
48
52
|
function planJson(root, file, edits) {
|
|
49
53
|
const text = readText(path.join(root, file));
|
|
50
54
|
const doc = readJson(text);
|
|
@@ -69,7 +73,7 @@ function planJson(root, file, edits) {
|
|
|
69
73
|
return {
|
|
70
74
|
file,
|
|
71
75
|
status: text === null ? 'create' : 'update',
|
|
72
|
-
reason: null,
|
|
76
|
+
reason: text === null ? null : shortfalls(edits.map(edit => (edit.kind === 'json' ? edit.shortfall?.(doc) : null))),
|
|
73
77
|
desired: { kind: 'text', text: `${JSON.stringify(next, null, text === null ? 2 : indentOf(text))}\n` },
|
|
74
78
|
edits,
|
|
75
79
|
};
|
|
@@ -81,7 +85,7 @@ function planToml(root, file, edits) {
|
|
|
81
85
|
for (const edit of edits) {
|
|
82
86
|
if (edit.kind !== 'toml')
|
|
83
87
|
continue;
|
|
84
|
-
const result = edit.
|
|
88
|
+
const result = edit.entries === null ? removeTable(next, edit.table) : upsertTable(next, edit.table, edit.entries);
|
|
85
89
|
if (result.kind === 'refused')
|
|
86
90
|
return refused(file, edits, result.reason);
|
|
87
91
|
if (result.kind === 'changed') {
|
|
@@ -91,7 +95,13 @@ function planToml(root, file, edits) {
|
|
|
91
95
|
}
|
|
92
96
|
if (!changed)
|
|
93
97
|
return { file, status: 'unchanged', reason: null, desired: null, edits };
|
|
94
|
-
return {
|
|
98
|
+
return {
|
|
99
|
+
file,
|
|
100
|
+
status: text === null ? 'create' : 'update',
|
|
101
|
+
reason: text === null ? null : shortfalls(edits.map(edit => (edit.kind === 'toml' ? edit.shortfall?.(text) : null))),
|
|
102
|
+
desired: { kind: 'text', text: next },
|
|
103
|
+
edits,
|
|
104
|
+
};
|
|
95
105
|
}
|
|
96
106
|
function planStub(root, edit) {
|
|
97
107
|
const text = readText(path.join(root, edit.file));
|
|
@@ -192,24 +202,26 @@ export function planInit(root, agents, skills, env) {
|
|
|
192
202
|
const byFile = new Map();
|
|
193
203
|
for (const edit of edits)
|
|
194
204
|
byFile.set(edit.file, [...(byFile.get(edit.file) ?? []), edit]);
|
|
195
|
-
const files = [...byFile].flatMap(([file, group]) =>
|
|
196
|
-
const [first] = group;
|
|
197
|
-
if (first?.kind === 'stub')
|
|
198
|
-
return [planStub(root, first)];
|
|
199
|
-
if (first?.kind === 'link')
|
|
200
|
-
return [planLink(root, first)];
|
|
201
|
-
if (first?.kind === 'unlink') {
|
|
202
|
-
const removal = planUnlink(root, first);
|
|
203
|
-
return removal ? [removal] : [];
|
|
204
|
-
}
|
|
205
|
-
if (first?.kind === 'toml')
|
|
206
|
-
return [planToml(root, file, group)];
|
|
207
|
-
const plan = planJson(root, file, group);
|
|
208
|
-
const cleanupOnly = group.every(edit => edit.kind === 'json' && edit.cleanup === true);
|
|
209
|
-
return cleanupOnly && plan.status === 'unchanged' ? [] : [plan];
|
|
210
|
-
});
|
|
205
|
+
const files = [...byFile].flatMap(([file, group]) => planFile(root, file, group));
|
|
211
206
|
return { root, agents: [...agents], claudePlugin, files };
|
|
212
207
|
}
|
|
208
|
+
/** What init would do to one file with these edits, all of which name that file. */
|
|
209
|
+
export function planFile(root, file, group) {
|
|
210
|
+
const [first] = group;
|
|
211
|
+
if (first?.kind === 'stub')
|
|
212
|
+
return [planStub(root, first)];
|
|
213
|
+
if (first?.kind === 'link')
|
|
214
|
+
return [planLink(root, first)];
|
|
215
|
+
if (first?.kind === 'unlink') {
|
|
216
|
+
const removal = planUnlink(root, first);
|
|
217
|
+
return removal ? [removal] : [];
|
|
218
|
+
}
|
|
219
|
+
if (first?.kind === 'toml')
|
|
220
|
+
return [planToml(root, file, group)];
|
|
221
|
+
const plan = planJson(root, file, group);
|
|
222
|
+
const cleanupOnly = group.every(edit => edit.kind === 'json' && edit.cleanup === true);
|
|
223
|
+
return cleanupOnly && plan.status === 'unchanged' ? [] : [plan];
|
|
224
|
+
}
|
|
213
225
|
function backup(root, file, into) {
|
|
214
226
|
const from = path.join(root, file);
|
|
215
227
|
try {
|
package/dist/agents/launcher.js
CHANGED
|
@@ -19,6 +19,8 @@ export const GUARDED_WORDS = [
|
|
|
19
19
|
'playwright-cli',
|
|
20
20
|
'@playwright/cli',
|
|
21
21
|
'agent-browser',
|
|
22
|
+
'docker',
|
|
23
|
+
'podman',
|
|
22
24
|
];
|
|
23
25
|
/**
|
|
24
26
|
* The hook's input arrives as JSON, which writes a backslash as `\\` and a newline as `\n`, and Copilot's `toolArgs` is
|
|
@@ -39,7 +41,7 @@ function worktreeFallback() {
|
|
|
39
41
|
/**
|
|
40
42
|
* The command an agent's hook runs: the project's own toolkit, found from the folder the hook runs in upwards, else in
|
|
41
43
|
* the first worktree of the same repository that has one. The guard starts the toolkit only for a command that names
|
|
42
|
-
* a device or
|
|
44
|
+
* a device, browser or container tool. Without a toolkit it allows and exits 0, because Copilot denies the tool call on any other
|
|
43
45
|
* exit and Gemini on exit 2 or more, and Cursor needs a JSON answer.
|
|
44
46
|
*/
|
|
45
47
|
export function hookCommand(agent, event) {
|
package/dist/agents/toml.js
CHANGED
|
@@ -230,8 +230,9 @@ class Scanner {
|
|
|
230
230
|
this.fail("a key needs '=' and a value");
|
|
231
231
|
this.advance();
|
|
232
232
|
this.spaces();
|
|
233
|
+
const start = this.pos;
|
|
233
234
|
this.value();
|
|
234
|
-
keys.push({ path: [...table, ...key], table, line });
|
|
235
|
+
keys.push({ path: [...table, ...key], table, line, end: this.line, value: this.text.slice(start, this.pos) });
|
|
235
236
|
this.endOfLine();
|
|
236
237
|
}
|
|
237
238
|
}
|
|
@@ -248,17 +249,11 @@ function same(a, b) {
|
|
|
248
249
|
function bare(part) {
|
|
249
250
|
return /^[A-Za-z0-9_-]+$/.test(part) ? part : JSON.stringify(part);
|
|
250
251
|
}
|
|
251
|
-
function lines(block) {
|
|
252
|
-
return block
|
|
253
|
-
.split('\n')
|
|
254
|
-
.map(line => line.trim())
|
|
255
|
-
.filter(line => line !== '' && !line.startsWith('#'));
|
|
256
|
-
}
|
|
257
252
|
/**
|
|
258
|
-
* Sets one table, `[a.b]
|
|
259
|
-
* sub-tables (`[a.b.env]`)
|
|
253
|
+
* Sets each entry's key in one table, `[a.b]`, adding the table when the file lacks it, and leaves every other line of
|
|
254
|
+
* the file as it was, the table's other keys and its sub-tables (`[a.b.env]`) included.
|
|
260
255
|
*/
|
|
261
|
-
export function upsertTable(text, table,
|
|
256
|
+
export function upsertTable(text, table, entries) {
|
|
262
257
|
let outline;
|
|
263
258
|
try {
|
|
264
259
|
outline = outlineToml(text);
|
|
@@ -271,23 +266,42 @@ export function upsertTable(text, table, body) {
|
|
|
271
266
|
if (ours.length > 1 || ours.some(h => h.array))
|
|
272
267
|
return { kind: 'refused', reason: `it declares [${name}] more than once` };
|
|
273
268
|
const own = ours[0];
|
|
274
|
-
const next = own ? outline.headers.find(h => h.line > own.line) : undefined;
|
|
275
269
|
const foreign = outline.keys.find(k => (startsWith(k.path, table) || startsWith(table, k.path)) && !startsWith(k.table, table));
|
|
276
270
|
if (foreign)
|
|
277
271
|
return { kind: 'refused', reason: `line ${String(foreign.line)} sets ${foreign.path.join('.')} outside [${name}]` };
|
|
278
|
-
const
|
|
279
|
-
const block = `[${name}]\n${body}`;
|
|
272
|
+
const set = (entry) => `${bare(entry.key)} = ${entry.value}`;
|
|
280
273
|
if (!own) {
|
|
281
274
|
const head = text === '' ? '' : text.endsWith('\n') ? `${text}\n` : `${text}\n\n`;
|
|
282
|
-
return { kind: 'changed', text: `${head}${
|
|
275
|
+
return { kind: 'changed', text: `${head}${[`[${name}]`, ...entries.map(set)].join('\n')}\n` };
|
|
276
|
+
}
|
|
277
|
+
const keys = outline.keys.filter(k => same(k.table, table));
|
|
278
|
+
const replaced = new Map();
|
|
279
|
+
const dropped = new Set();
|
|
280
|
+
const added = [];
|
|
281
|
+
for (const entry of entries) {
|
|
282
|
+
const found = keys.filter(k => k.path[table.length] === entry.key);
|
|
283
|
+
const [first] = found;
|
|
284
|
+
if (!first) {
|
|
285
|
+
added.push(set(entry));
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
const whole = found.length === 1 && first.path.length === table.length + 1;
|
|
289
|
+
if (whole && (first.value === entry.value || entry.keeps?.(first.value) === true))
|
|
290
|
+
continue;
|
|
291
|
+
for (const key of found)
|
|
292
|
+
for (let line = key.line; line <= key.end; line++)
|
|
293
|
+
dropped.add(line);
|
|
294
|
+
replaced.set(first.line, set(entry));
|
|
283
295
|
}
|
|
284
|
-
|
|
285
|
-
while (end > own.line && /^\s*(#.*)?$/.test(all[end - 1] ?? ''))
|
|
286
|
-
end--;
|
|
287
|
-
const current = all.slice(own.line - 1, end).join('\n');
|
|
288
|
-
if (lines(current).join('\n') === lines(block).join('\n'))
|
|
296
|
+
if (replaced.size === 0 && added.length === 0)
|
|
289
297
|
return { kind: 'unchanged' };
|
|
290
|
-
|
|
298
|
+
const after = Math.max(own.line, ...keys.map(k => k.end));
|
|
299
|
+
const next = text.split('\n').flatMap((line, i) => {
|
|
300
|
+
const at = i + 1;
|
|
301
|
+
const kept = replaced.get(at) ?? (dropped.has(at) ? null : line);
|
|
302
|
+
return [...(kept === null ? [] : [kept]), ...(at === after ? added : [])];
|
|
303
|
+
});
|
|
304
|
+
return { kind: 'changed', text: next.join('\n') };
|
|
291
305
|
}
|
|
292
306
|
/** Removes one table, `[a.b]`, with its own sub-tables, and leaves every other line of the file as it was. */
|
|
293
307
|
export function removeTable(text, table) {
|
|
@@ -3,7 +3,7 @@ import path from 'node:path';
|
|
|
3
3
|
import { CLI, TOOL } from "../name.js";
|
|
4
4
|
import { AGENTS } from "../registry/owner.js";
|
|
5
5
|
import { CLAUDE_SETTINGS, claudePluginInstall, describePluginSource, jsonObjectAt } from "./claude-plugin.js";
|
|
6
|
-
import { planInit } from "./init.js";
|
|
6
|
+
import { planFile, planInit } from "./init.js";
|
|
7
7
|
import { listSkills, SKILLS_DIR } from "./skills.js";
|
|
8
8
|
import { agentEdits, disablesOurServer, pluginEnabled } from "./wiring.js";
|
|
9
9
|
const SHARED = new Set(['.mcp.json']);
|
|
@@ -37,7 +37,7 @@ function problem(file) {
|
|
|
37
37
|
case 'create':
|
|
38
38
|
return `missing ${file.file} (${parts})`;
|
|
39
39
|
case 'update':
|
|
40
|
-
return `stale ${file.file} (${parts})`;
|
|
40
|
+
return `stale ${file.file} (${parts})${file.reason === null ? '' : `: ${file.reason}`}`;
|
|
41
41
|
case 'remove':
|
|
42
42
|
return `duplicate ${file.file} (${parts})`;
|
|
43
43
|
case 'refused':
|
|
@@ -46,6 +46,15 @@ function problem(file) {
|
|
|
46
46
|
return '';
|
|
47
47
|
}
|
|
48
48
|
}
|
|
49
|
+
/** The part of a file's plan that the agent's own edits make, so its line names only what `init --agents <agent>` changes. */
|
|
50
|
+
function ownShare(root, file, agent) {
|
|
51
|
+
const own = file.edits.filter(e => e.agent === agent);
|
|
52
|
+
if (own.length === 0)
|
|
53
|
+
return [];
|
|
54
|
+
if (own.length === file.edits.length)
|
|
55
|
+
return [file];
|
|
56
|
+
return planFile(root, file.file, own).filter(f => f.status !== 'unchanged');
|
|
57
|
+
}
|
|
49
58
|
function check(name, problems, fine, fix) {
|
|
50
59
|
return problems.length === 0
|
|
51
60
|
? { name, ok: true, warning: false, detail: fine, fix: '' }
|
|
@@ -83,7 +92,7 @@ export function agentWiringChecks(root, env, skills = listSkills(SKILLS_DIR)) {
|
|
|
83
92
|
if (plan.files.some(f => f.edits.some(e => e.kind === 'stub')))
|
|
84
93
|
checks.push(check('wiring skills', off.filter(f => f.edits.every(e => e.agent === null)), `${String(skills.length)} skill stubs in .agents/skills`, fix));
|
|
85
94
|
for (const agent of agents) {
|
|
86
|
-
const mine = off.
|
|
95
|
+
const mine = off.flatMap(f => ownShare(root, f, agent));
|
|
87
96
|
const plugin = agent === 'claude' ? plan.claudePlugin : null;
|
|
88
97
|
const fine = plugin ? `through the plugin: ${describePluginSource(plugin)}` : 'MCP server and hooks in place';
|
|
89
98
|
const line = check(`wiring ${agent}`, mine, fine, `${CLI} init --agents ${agent}`);
|