agentlane 0.4.1 → 0.5.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 +87 -0
- package/dist/agents/claude-plugin.js +69 -8
- package/dist/agents/cli.js +11 -4
- package/dist/agents/hook-check.js +290 -0
- package/dist/agents/launcher.js +34 -6
- package/dist/agents/wiring-check.js +10 -4
- package/dist/agents/wiring.js +6 -33
- package/dist/browser/env.js +27 -7
- package/dist/browser/install.js +144 -6
- package/dist/browser/lane-browser.js +6 -3
- package/dist/browser/stop.js +2 -17
- package/dist/cache/key.js +23 -11
- package/dist/cli.js +63 -23
- package/dist/devices/backend.js +6 -0
- package/dist/devices/emulator.js +15 -5
- package/dist/devices/hygiene.js +20 -4
- package/dist/devices/simctl.js +15 -3
- package/dist/disk-limits.js +134 -0
- package/dist/driver/caller.js +21 -6
- package/dist/driver/client.js +9 -5
- package/dist/driver/engine.js +29 -14
- package/dist/driver/install.js +88 -36
- package/dist/driver/paths.js +15 -11
- package/dist/driver/session.js +4 -1
- package/dist/driver/superseded.js +378 -0
- package/dist/driver-cli.js +32 -23
- package/dist/evidence/device.js +4 -0
- package/dist/evidence/evidence.js +4 -2
- package/dist/evidence/files.js +68 -0
- package/dist/evidence/strays.js +107 -0
- package/dist/hooks/env.js +2 -1
- package/dist/mcp/server.js +15 -0
- package/dist/mcp/tools.js +9 -1
- package/dist/plugin/guard.js +30 -0
- package/dist/plugin/hook-cli.js +101 -6
- package/dist/plugin/hook-mark.js +73 -0
- package/dist/plugin/hook-once.js +78 -0
- package/dist/plugin/shell.js +109 -8
- package/dist/processes.js +52 -2
- package/dist/registry/config.js +12 -8
- package/dist/registry/holds.js +37 -0
- package/dist/registry/leases.js +109 -0
- package/dist/registry/owner-checks.js +55 -0
- package/dist/registry/owner.js +18 -0
- package/dist/registry/parks.js +60 -0
- package/dist/registry/paths.js +28 -4
- package/dist/registry/ports.js +5 -1
- package/dist/registry/prune.js +643 -24
- package/dist/registry/refusal.js +1 -0
- package/dist/registry/registry.js +1261 -236
- package/dist/registry/rows.js +18 -4
- package/dist/registry/status.js +51 -8
- package/dist/registry/store.js +65 -2
- package/dist/registry/touch.js +180 -0
- package/dist/registry-cli.js +197 -36
- package/dist/services/services.js +227 -56
- package/dist/services/system.js +2 -1
- package/dist/up/answers.js +124 -0
- package/dist/up/doctor.js +29 -4
- package/dist/up/exec.js +29 -4
- package/dist/up/lane-files.js +26 -8
- package/dist/up/lane-services.js +8 -3
- package/dist/up/park.js +146 -0
- package/dist/up/preflight.js +2 -10
- package/dist/up/release.js +20 -24
- package/dist/up/restart.js +9 -2
- package/dist/up/sweep.js +437 -0
- package/dist/up/up.js +38 -15
- package/dist/up/wake.js +124 -0
- package/dist/up/waker.js +49 -0
- package/dist/up-cli.js +6 -1
- package/package.json +2 -2
- package/skills/dev-loop/SKILL.md +7 -5
- package/skills/drive/SKILL.md +4 -0
- package/skills/setup/SKILL.md +2 -2
package/dist/up/wake.js
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { systemClock } from "../clock.js";
|
|
2
|
+
import { DriverError, messageOf } from "../driver/errors.js";
|
|
3
|
+
import { CLI, TOOL } from "../name.js";
|
|
4
|
+
import { formatAge, formatTime } from "../registry/format.js";
|
|
5
|
+
import { describeRestarts } from "../registry/parks.js";
|
|
6
|
+
import { tcpProbe } from "../registry/ports.js";
|
|
7
|
+
import { NotClaimed, Refusal } from "../registry/refusal.js";
|
|
8
|
+
import { Registry } from "../registry/registry.js";
|
|
9
|
+
import { wakeFolder } from "./lane-files.js";
|
|
10
|
+
import { attemptId, deadHolder } from "./park.js";
|
|
11
|
+
/** How long a call waits on another call parking or waking its lane. */
|
|
12
|
+
export const LANE_WAIT_MS = 30 * 60_000;
|
|
13
|
+
function openRegistry(entry) {
|
|
14
|
+
return Registry.open({
|
|
15
|
+
dir: entry.stateDir,
|
|
16
|
+
processes: entry.processes,
|
|
17
|
+
ports: tcpProbe,
|
|
18
|
+
devices: {},
|
|
19
|
+
...(entry.clock ? { clock: entry.clock } : {}),
|
|
20
|
+
...(entry.self ? { self: entry.self } : {}),
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
function stillBusy(ref, worktree, park, waitedMs) {
|
|
24
|
+
const woken = park.state === 'waking';
|
|
25
|
+
const pid = park.holder?.pid;
|
|
26
|
+
return new Refusal('lane-busy', `lane ${ref.id} is still being ${woken ? 'brought back' : 'parked'} by another call, ${formatAge(waitedMs)} after this one began waiting`, [
|
|
27
|
+
{
|
|
28
|
+
who: `a process ${woken ? 'bringing the lane back' : 'parking the lane'} (pid ${String(pid ?? 'unknown')})`,
|
|
29
|
+
folder: worktree,
|
|
30
|
+
since: formatTime(park.since),
|
|
31
|
+
},
|
|
32
|
+
], [
|
|
33
|
+
`retry the same ${TOOL} command once it finishes`,
|
|
34
|
+
`${CLI} status (the lane, and the process parking or waking it)`,
|
|
35
|
+
...(pid === undefined
|
|
36
|
+
? []
|
|
37
|
+
: [`kill ${String(pid)} (only if that process is hung; the next call then takes the lane over)`]),
|
|
38
|
+
]);
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* For a call on a lane its owner holds, once the call is recorded: waits out a park or wake of the lane another call
|
|
42
|
+
* runs, then takes the lane for waking if it is parked, so no other call wakes it meanwhile. Null when it is awake.
|
|
43
|
+
*/
|
|
44
|
+
export async function takeLane(entry, ref) {
|
|
45
|
+
const clock = entry.clock ?? systemClock;
|
|
46
|
+
const started = clock.now();
|
|
47
|
+
const registry = openRegistry(entry);
|
|
48
|
+
try {
|
|
49
|
+
for (;;) {
|
|
50
|
+
const seen = registry.parkOf(ref.id);
|
|
51
|
+
if (!seen)
|
|
52
|
+
return null;
|
|
53
|
+
const attempt = attemptId();
|
|
54
|
+
const start = registry.beginWake(ref, attempt, deadHolder(seen, entry.processes));
|
|
55
|
+
if (start.kind === 'awake')
|
|
56
|
+
return null;
|
|
57
|
+
if (start.kind === 'taken')
|
|
58
|
+
return { ref, attempt, park: start.park };
|
|
59
|
+
const waited = clock.now() - started;
|
|
60
|
+
if (waited >= (entry.waitMs ?? LANE_WAIT_MS))
|
|
61
|
+
throw stillBusy(ref, start.worktree, start.park, waited);
|
|
62
|
+
await clock.sleep(entry.pollMs ?? 250);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
finally {
|
|
66
|
+
registry.close();
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/** Ends a wake: the lane is awake when `failure` is null, and parked again with the failure otherwise. */
|
|
70
|
+
export function settleWake(entry, handle, failure) {
|
|
71
|
+
const registry = openRegistry(entry);
|
|
72
|
+
try {
|
|
73
|
+
if (failure === null)
|
|
74
|
+
registry.finishWake(handle.ref, handle.attempt);
|
|
75
|
+
else
|
|
76
|
+
registry.giveUp(handle.ref, handle.attempt, [`the last call could not bring it back: ${messageOf(failure)}`]);
|
|
77
|
+
}
|
|
78
|
+
finally {
|
|
79
|
+
registry.close();
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
let waking = Promise.resolve();
|
|
83
|
+
function oneAtATime(work) {
|
|
84
|
+
const next = waking.then(work, work);
|
|
85
|
+
waking = next.catch(() => undefined);
|
|
86
|
+
return next;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Makes sure a lane is awake before a call on it runs, the call having been recorded before `park` was read: waits out
|
|
90
|
+
* a park or wake another call runs, and wakes the lane with `wake` if it is parked. Returns the lane as it is then.
|
|
91
|
+
*/
|
|
92
|
+
export async function enterLane(entry, lane, park, wake, log = () => undefined) {
|
|
93
|
+
if (!park)
|
|
94
|
+
return lane;
|
|
95
|
+
if (!wake) {
|
|
96
|
+
throw new NotClaimed(`lane ${lane.id} is parked: it went unused, so its device went back to the pool and its services stopped, and this call can't bring them back`, `${CLI} up (run in ${wakeFolder(entry.stateDir, lane)}; it brings back ${describeRestarts(park.restarts)})`);
|
|
97
|
+
}
|
|
98
|
+
const handle = await takeLane(entry, { id: lane.id, token: lane.token });
|
|
99
|
+
if (handle) {
|
|
100
|
+
const since = handle.park.parkedAt === null ? '' : ` ${formatAge((entry.clock ?? systemClock).now() - handle.park.parkedAt)} ago`;
|
|
101
|
+
log(`lane ${lane.id} was parked${since}; bringing back ${describeRestarts(handle.park.restarts)}`);
|
|
102
|
+
let failure = null;
|
|
103
|
+
try {
|
|
104
|
+
await oneAtATime(() => wake(lane, handle.park));
|
|
105
|
+
}
|
|
106
|
+
catch (error) {
|
|
107
|
+
failure = error;
|
|
108
|
+
}
|
|
109
|
+
settleWake(entry, handle, failure);
|
|
110
|
+
if (failure !== null) {
|
|
111
|
+
throw new DriverError(`could not bring lane ${lane.id} back: ${messageOf(failure)}`, `fix that and call again: the lane stays parked, and its next call tries again (${CLI} up in ${wakeFolder(entry.stateDir, lane)} shows each step)`);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
const registry = openRegistry(entry);
|
|
115
|
+
try {
|
|
116
|
+
const now = registry.find(lane.owner, lane.worktree);
|
|
117
|
+
if (now?.id !== lane.id)
|
|
118
|
+
throw new NotClaimed(`lane ${lane.id} has ended`, `${CLI} up (run in ${lane.worktree})`);
|
|
119
|
+
return now;
|
|
120
|
+
}
|
|
121
|
+
finally {
|
|
122
|
+
registry.close();
|
|
123
|
+
}
|
|
124
|
+
}
|
package/dist/up/waker.js
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { stateDir } from "../registry/paths.js";
|
|
2
|
+
import { Registry } from "../registry/registry.js";
|
|
3
|
+
import { laneDir, readUpRecord, wakeFolder } from "./lane-files.js";
|
|
4
|
+
import { up } from "./up.js";
|
|
5
|
+
/** How long waking a lane waits for a pool device, as `up` does by default. */
|
|
6
|
+
export const WAKE_WAIT_MS = 600_000;
|
|
7
|
+
/**
|
|
8
|
+
* Wakes a lane through the steps `up` takes, minus setup and resource creation, for each platform `up` brought it up
|
|
9
|
+
* for; a lane `up` never ran for gets its device back, booted if it was.
|
|
10
|
+
*/
|
|
11
|
+
export function upWaker(deps) {
|
|
12
|
+
return async (lane, park) => {
|
|
13
|
+
const state = stateDir(deps.env);
|
|
14
|
+
const record = readUpRecord(laneDir(state, lane.id));
|
|
15
|
+
if (record) {
|
|
16
|
+
const folder = wakeFolder(state, lane);
|
|
17
|
+
for (const platform of record.platforms ?? [record.platform]) {
|
|
18
|
+
await up({ ...deps, cwd: folder }, { setup: false, cacheMode: 'use', waitMs: WAKE_WAIT_MS, worktree: folder, platform, waking: true });
|
|
19
|
+
}
|
|
20
|
+
return;
|
|
21
|
+
}
|
|
22
|
+
const device = park.restarts.device;
|
|
23
|
+
if (!device)
|
|
24
|
+
return;
|
|
25
|
+
const registry = Registry.open({
|
|
26
|
+
dir: state,
|
|
27
|
+
processes: deps.processes,
|
|
28
|
+
ports: deps.ports,
|
|
29
|
+
devices: deps.devices,
|
|
30
|
+
clock: deps.clock,
|
|
31
|
+
...(deps.pollMs !== undefined ? { pollMs: deps.pollMs } : {}),
|
|
32
|
+
});
|
|
33
|
+
try {
|
|
34
|
+
await registry.claim({
|
|
35
|
+
owner: lane.owner,
|
|
36
|
+
worktree: lane.worktree,
|
|
37
|
+
projectRoot: lane.projectRoot,
|
|
38
|
+
services: [],
|
|
39
|
+
device: { platform: device.platform, deviceType: device.deviceType, runtime: device.runtime, prefer: device.name },
|
|
40
|
+
waitMs: WAKE_WAIT_MS,
|
|
41
|
+
boot: device.booted,
|
|
42
|
+
action: 'wake',
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
finally {
|
|
46
|
+
registry.close();
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
}
|
package/dist/up-cli.js
CHANGED
|
@@ -13,6 +13,7 @@ import { ownerKey, resolveOwner } from "./registry/owner.js";
|
|
|
13
13
|
import { stateDir } from "./registry/paths.js";
|
|
14
14
|
import { NotClaimed, Refusal, UsageError } from "./registry/refusal.js";
|
|
15
15
|
import { readRegistryStatus } from "./registry/registry.js";
|
|
16
|
+
import { touchOwnLane } from "./registry/touch.js";
|
|
16
17
|
import { resolveFolder } from "./registry-cli.js";
|
|
17
18
|
import { ServiceFailed } from "./services/services.js";
|
|
18
19
|
import { laneDir, readUpRecord } from "./up/lane-files.js";
|
|
@@ -190,10 +191,13 @@ async function runDoctor(args, deps, stdout) {
|
|
|
190
191
|
});
|
|
191
192
|
const asked = parsePlatform(values.platform);
|
|
192
193
|
const folder = resolveFolder(deps.cwd);
|
|
193
|
-
const
|
|
194
|
+
const owner = resolveOwner(deps.env, deps.processes, deps.selfPid);
|
|
195
|
+
const key = ownerKey(owner);
|
|
194
196
|
const state = stateDir(deps.env);
|
|
195
197
|
const status = readRegistryStatus({ dir: state, processes: deps.processes, devices: deps.devices, clock: deps.clock });
|
|
196
198
|
const lane = status.lanes.find(c => c.ownerKey === key && c.worktree === folder.worktree) ?? null;
|
|
199
|
+
if (lane)
|
|
200
|
+
touchOwnLane({ dir: state, processes: deps.processes, clock: deps.clock }, owner, folder.worktree, 'doctor');
|
|
197
201
|
let config = null;
|
|
198
202
|
let configProblem = null;
|
|
199
203
|
const record = lane ? readUpRecord(laneDir(state, lane.id)) : null;
|
|
@@ -218,6 +222,7 @@ async function runDoctor(args, deps, stdout) {
|
|
|
218
222
|
folder: folder.worktree,
|
|
219
223
|
platform: asked,
|
|
220
224
|
installed: record?.installed,
|
|
225
|
+
park: lane?.park ?? null,
|
|
221
226
|
});
|
|
222
227
|
stdout(values.json ? `${JSON.stringify(result, null, 2)}\n` : renderDoctor(result));
|
|
223
228
|
return result.ok ? 0 : EXIT_FAILED;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentlane",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "Gives each coding agent its own lane: a running copy of your app with its own ports, dev servers, database, and a simulator, emulator or browser to drive it.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai-agents",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"lint": "eslint . && prettier --check .",
|
|
44
44
|
"lint:sh": "git ls-files -z '*.sh' | xargs -0 -r shellcheck",
|
|
45
45
|
"typecheck": "tsc -p tsconfig.json",
|
|
46
|
-
"test": "node --test 'tests/**/*.test.ts'",
|
|
46
|
+
"test": "node --import ./tests/support/isolate.ts --test 'tests/**/*.test.ts'",
|
|
47
47
|
"schema": "node src/cli.ts schema > schema/agentlane.schema.json",
|
|
48
48
|
"hero": "node scripts/hero/generate.ts",
|
|
49
49
|
"site": "node site/build/build.ts"
|
package/skills/dev-loop/SKILL.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dev-loop
|
|
3
|
-
description: The contract for running a project's app as an agent with the toolkit - one lane per session and folder (a simulator or emulator, a browser, the ports for Metro, the API and the web app, and per-lane resources such as a database), `agentlane up` from bare worktree to running app, `doctor` before trusting an instance, `release` when done - plus what a project's run skill holds and what counts as proof and evidence from a running app. Use when about to run, build, launch or capture a project's mobile or web app, start its dev servers, hand an agent work that runs the app, or when an agent loses turns to ports, simulators, browsers, databases or half-started servers.
|
|
4
|
-
when_to_use: Booting a simulator or emulator, opening the web app in a browser, starting Metro or a dev server, running the app for verification, capture, e2e or debugging; dispatching agents that will run the app; a project with no agentlane.json or no run skill. Not for test-only work that never runs the app.
|
|
3
|
+
description: The contract for running a project's app as an agent with the toolkit - one lane per session and folder (a simulator or emulator, a browser, the ports for Metro, the API and the web app, and per-lane resources such as a database), `agentlane up` from bare worktree to running app, `doctor` before trusting an instance, `keep` while the user looks at the running app, `release` when done - plus what a project's run skill holds and what counts as proof and evidence from a running app. Use when about to run, build, launch or capture a project's mobile or web app, start its dev servers, hand an agent work that runs the app, or when an agent loses turns to ports, simulators, browsers, databases or half-started servers.
|
|
4
|
+
when_to_use: Booting a simulator or emulator, opening the web app in a browser, starting Metro or a dev server, running the app for verification, capture, e2e or debugging; leaving the running app for the user to look at; dispatching agents that will run the app; a project with no agentlane.json or no run skill. Not for test-only work that never runs the app.
|
|
5
5
|
license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyright (c) 2026 Lauren Tan; the full notice is in LICENSE beside this skill in the toolkit package
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -11,7 +11,7 @@ license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyr
|
|
|
11
11
|
|
|
12
12
|
Every agent session gets its own running copy of the project, mobile app or web app: its own simulator or emulator, its own browser, its own ports for Metro, the API and the web server, its own resources such as a database, and its own processes on them. The toolkit keeps that in one registry per machine, shared by every project and every agent, so two agents never build onto the same simulator, sign in through the same browser profile, bind the same port or write to the same per-lane database. Everything here runs from a shell at the project root, as `node_modules/.bin/agentlane <command>`: that path works in every agent's shell, while a bare `agentlane` is on the PATH only in Claude Code with the toolkit's plugin. In a fresh worktree with no `node_modules` yet, run the project's install command first. The project's specifics live in its `agentlane.json` (`node_modules/.bin/agentlane schema` prints the format) and its run skill.
|
|
13
13
|
|
|
14
|
-
The loop is done when you have run `release` in your folder, and what you claim about the app rests on a replayable run whose evidence is where you say it is.
|
|
14
|
+
The loop is done when you have run `release` in your folder, or held the lane with `keep` for the user to look at the running app, and what you claim about the app rests on a replayable run whose evidence is where you say it is.
|
|
15
15
|
|
|
16
16
|
## The loop
|
|
17
17
|
|
|
@@ -26,9 +26,11 @@ The loop is done when you have run `release` in your folder, and what you claim
|
|
|
26
26
|
3. **Work.** `node_modules/.bin/agentlane exec -- <command>` runs a command with the lane's variables: `AGENTLANE_DEVICE`, `AGENTLANE_<SERVICE>_PORT`, `AGENTLANE_WEB_URL`, the resources' values, the browser driver's session and `AGENTLANE_STORAGE_STATE`, the log folder `AGENTLANE_LOGS` and the evidence folder `AGENTLANE_EVIDENCE`. An agent's shell commands often start with a fresh environment, so prefer `exec` over exporting. Drive the app with the `drive` skill: the device tools on a device, the driver's own CLI under `exec` in the browser, `look` and `screenshot` on both. To change a service's environment, such as a feature switch, an admin toggle or a client gate, run `KEY=value node_modules/.bin/agentlane restart <service>` rather than `release` and `up`, which would cost a re-lane, an install and a sign-in. It restarts only that service, on the same port, and returns once its ready check passes; the lane, the device, the browser, the app and the other services stay as they are. The service gets the lane's variables plus that call's environment, so pass every variable you still want: one given to `up` and not to `restart` is gone.
|
|
27
27
|
4. **`node_modules/.bin/agentlane release`** in the same folder when you're done: it stops exactly the processes `up` started, the browser and its driver's daemons included, runs the project's teardown and each resource's teardown (the lane's database is gone after this), and frees the lane. The evidence folder stays. When the session ends, its remaining lanes are released for it.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
When you hand the running app to the user to look at, hold the lane before you end your turn, and release it once they are done: `node_modules/.bin/agentlane keep --for 2h --reason "<who is looking at what>"`. Without a hold, the lane is parked 30 minutes after your last call, and the user finds the simulator shut down or the web app's servers stopped. `--for` takes minutes or hours (`45m`, `2h`, `1h30m`), one hour when left out and 24 at most, so size it to how long they will look. Say in your message that the lane is held and until when, so they know the app waits for them. Running `keep` again replaces the hold, and `release` or the end of your session ends it.
|
|
30
30
|
|
|
31
|
-
`node_modules/.bin/agentlane
|
|
31
|
+
`node_modules/.bin/agentlane status` lists every lane on the machine with its owner, folder, start, idle time, last action and any hold. A lane whose session exited without releasing it, after a crash for instance, is parked within minutes and ends 30 minutes later, its resources torn down with it. Until then the same Claude Code session or Codex thread takes it back, data intact, by calling on it from its folder, so a resumed session finds its lane. With the pool full, `claim` and `up` wait in a queue. A lane nobody holds is parked 30 minutes after its last call: its servers stop and its device goes back to the pool, while its ports, resources and record stay, and the next call such as `exec`, `look` or `up` brings it back with the same data before it runs. No lane takes over another.
|
|
32
|
+
|
|
33
|
+
`node_modules/.bin/agentlane prune` lists what takes disk and nothing uses, each with its size: the pool simulators and emulators no lane holds, shut-down devices named like pool devices that no registry records, and what agentlane 0.2.x left. `prune --yes` deletes it. Every project on the machine shares that pool, and the next lane after a prune waits while a new device is created, so run it when the user asks for disk space back; cleaning up after your own work is `release`.
|
|
32
34
|
|
|
33
35
|
## Lanes are per session and folder
|
|
34
36
|
|
package/skills/drive/SKILL.md
CHANGED
|
@@ -55,6 +55,10 @@ Prove a behaviour with an assertion: the committed flow or test above, checking
|
|
|
55
55
|
|
|
56
56
|
Each prints the file it wrote in the lane's evidence folder, `$AGENTLANE_EVIDENCE`, which outlives `release` by seven days; `node_modules/.bin/agentlane evidence list` shows what is there. A failed run, and a failed command under exec on a browser lane, keep their own bundle there (the trace, a screenshot, the page or screen, the console or driver log) without being asked. `maestro test` under exec or in a hook keeps its whole output there, its `takeScreenshot` files included, in a folder per run: `<stamp>-maestro-test-<pid>`, ending `-failed` when the test failed. Read that bundle before you retry, and name the files you cite in your report.
|
|
57
57
|
|
|
58
|
+
## When a person looks at the app
|
|
59
|
+
|
|
60
|
+
When you leave the app running for the user to look at, rather than sending them a video or a screenshot, hold your lane first: `node_modules/.bin/agentlane keep --for 2h --reason "<who is looking at what>"`. A lane nobody holds is parked 30 minutes after its last call, which shuts its simulator or emulator down and stops its web app. The hold lasts one hour when `--for` is left out and 24 hours at most. Say in your message that the lane is held and until when; `release` ends the hold once they are done.
|
|
61
|
+
|
|
58
62
|
## Device controls
|
|
59
63
|
|
|
60
64
|
Settings that aren't taps live in the CLI, on the same claimed device: `node_modules/.bin/agentlane device location <lat>,<lon> | clear`, `device permission grant|revoke|reset <service> [<bundle id>]`, `device appearance light|dark`, `device push <bundle id> <payload.json | ->`, `device clipboard set <text> | get` and `device open <url>`. On an emulator, `location clear`, `push` and `clipboard` have no adb equivalent and refuse with the reason; `permission` takes the package name and grants the Android permissions behind the service that the app declares.
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -40,7 +40,7 @@ Decide each of these from the survey, with a one-line reason you'll repeat in th
|
|
|
40
40
|
- **Data per lane or shared:** when the tests already create a local database (a Docker Postgres, SQLite, a local Supabase stack), give each lane its own copy as a resource: a database named after the lane, created, migrated and seeded the way the tests do, and dropped at teardown. When the project relies on a shared hosted database with no local equivalent, keep it shared, and have the run skill name what a write must clean up. When both are possible but they differ in a way the user cares about (local needs Docker, lacks an extension, or misses data only the hosted copy has), that is a trade-off to ask about.
|
|
41
41
|
- **Sign-in:** which account each lane signs in as, and through which seam. Prefer the app's own sign-in endpoint with a test account, called from the `signin` hook; on the web the hook writes the saved login the lane's browser starts with.
|
|
42
42
|
- **Browser driver:** Playwright, unless the project already drives browsers with agent-browser. When a person wants to watch the browser, Playwright with `web.browser.headed: true`, since agent-browser runs headless only. The project's `@playwright/test` must be the toolkit's Playwright version (`node_modules/.bin/agentlane browser status` names it), or its tests find no browser in a lane; moving the pin to that version is a change setup makes and reports, and a pin the project must keep for another reason is a question for the user.
|
|
43
|
-
- **Agents to wire:** the agent you are running in, and every agent whose folder the repo already commits. Wherever Claude Code loads the toolkit's plugin (the project's settings, the user's, or the session you run in), `init` leaves Claude Code to the plugin rather than writing a second copy
|
|
43
|
+
- **Agents to wire:** the agent you are running in, and every agent whose folder the repo already commits. Wherever Claude Code loads the toolkit's plugin (the project's settings, the user's, or the session you run in), `init` leaves Claude Code's skills and MCP server to the plugin rather than writing a second copy, and says which it found; it writes the hooks into `.claude/settings.json` either way, so they run where the plugin isn't installed. When only the user's settings or the session load the plugin, someone who opens the project without it gets no Claude Code skills or MCP server from the committed files; that goes in the summary with init's note.
|
|
44
44
|
|
|
45
45
|
Collect what only the user can answer as you go: a real trade-off, a credential or account you can't find or create, a hosted database the project must keep. Ask them in one message, after the survey, each with your recommended answer, and keep working on everything that doesn't depend on the answers. When no one can answer, as in a non-interactive run, take your recommendation and list it in the summary as an assumption.
|
|
46
46
|
|
|
@@ -48,7 +48,7 @@ This step is done when every decision above has an answer and a reason, and ever
|
|
|
48
48
|
|
|
49
49
|
## 4. Install the toolkit and wire the agents
|
|
50
50
|
|
|
51
|
-
Run `node_modules/.bin/agentlane init --agents <list>` (the names it takes: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `antigravity`). When `node_modules/.bin/agentlane` is missing at the project root, run `npx agentlane init --agents <list>` instead: init adds the toolkit to the project's `package.json` as a dev dependency with the project's package manager, creating a private `package.json` when there is none, and prints what it did, which goes in the summary. When it exits 1 because the install failed, run the command it prints and fix what stops it. When the user installs the toolkit from another source than npm (ask if the repo doesn't show one), add it from there before you run init. It writes each agent's skill stubs in `.agents/skills/` (mirrored into `.claude/skills/` for Claude Code), its MCP server entry and its hooks, backs up what it changes, and refuses a file it can't parse with nothing written; fix or report a refusal rather than editing around it. Keep the per-agent notes it prints for the summary: they are the trust prompts the user must accept. `node_modules/.bin/agentlane init --agents <list> --check` exits 0 once the wiring is complete.
|
|
51
|
+
Run `node_modules/.bin/agentlane init --agents <list>` (the names it takes: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `antigravity`). When `node_modules/.bin/agentlane` is missing at the project root, run `npx agentlane init --agents <list>` instead: init adds the toolkit to the project's `package.json` as a dev dependency with the project's package manager, creating a private `package.json` when there is none, and prints what it did, which goes in the summary. When it exits 1 because the install failed, run the command it prints and fix what stops it. When the user installs the toolkit from another source than npm (ask if the repo doesn't show one), add it from there before you run init. It writes each agent's skill stubs in `.agents/skills/` (mirrored into `.claude/skills/` for Claude Code), its MCP server entry and its hooks, backs up what it changes, and refuses a file it can't parse with nothing written; fix or report a refusal rather than editing around it. Keep the per-agent notes it prints for the summary: they are the trust prompts the user must accept. `node_modules/.bin/agentlane init --agents <list> --check` exits 0 once the wiring is complete. `doctor` then has a `hooks <agent>` line per agent: a failure there means that agent's guard doesn't run and its sessions' lanes aren't released when they end, so fix it the way the line says.
|
|
52
52
|
|
|
53
53
|
## 5. Write the config, the run skill and the flows
|
|
54
54
|
|