@phren/cli 0.3.79 → 0.3.80
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/dist/bridge/dispatch.js +17 -3
- package/dist/bridge/housekeeping/command.d.ts +5 -0
- package/dist/bridge/housekeeping/command.js +106 -0
- package/dist/bridge/housekeeping/housekeeper.d.ts +123 -0
- package/dist/bridge/housekeeping/housekeeper.js +459 -0
- package/dist/bridge/housekeeping/inventory.d.ts +145 -0
- package/dist/bridge/housekeeping/inventory.js +276 -0
- package/dist/bridge/housekeeping/report.d.ts +672 -0
- package/dist/bridge/housekeeping/report.js +168 -0
- package/dist/bridge/housekeeping/safety.d.ts +177 -0
- package/dist/bridge/housekeeping/safety.js +466 -0
- package/dist/bridge/owner-proof.js +1 -0
- package/dist/bridge/push.js +3 -1
- package/dist/bridge/resources.d.ts +8 -0
- package/dist/bridge/resources.js +18 -5
- package/dist/bridge/server-pane-routes.d.ts +6 -0
- package/dist/bridge/server-pane-routes.js +1 -1
- package/dist/bridge/server-routes.d.ts +5 -0
- package/dist/bridge/server-routes.js +44 -3
- package/dist/bridge/server.js +44 -8
- package/dist/bridge-hook.mjs +2980 -1226
- package/dist/cli-registry.js +18 -1
- package/dist/fanout/command.js +42 -15
- package/dist/heavy/budget-status.d.ts +26 -0
- package/dist/heavy/budget-status.js +26 -0
- package/dist/heavy/budget.d.ts +39 -0
- package/dist/heavy/budget.js +57 -0
- package/dist/heavy/command.d.ts +15 -0
- package/dist/heavy/command.js +119 -0
- package/dist/heavy/reap.d.ts +70 -0
- package/dist/heavy/reap.js +211 -0
- package/dist/heavy/slots.d.ts +58 -0
- package/dist/heavy/slots.js +142 -0
- package/dist/modules/registry.js +4 -3
- package/package.json +1 -1
- package/starter/global/skills/conductor/SKILL.md +10 -0
- package/starter/global/skills/fanout/SKILL.md +30 -0
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
import * as path from "node:path";
|
|
4
|
+
import { promisify } from "node:util";
|
|
5
|
+
import { parseEtime, parsePs, withStartTimes } from "../bridge/resources.js";
|
|
6
|
+
import { minutes, slotsRoot } from "./slots.js";
|
|
7
|
+
const exec = promisify(execFile);
|
|
8
|
+
const SHELLS = new Set(["sh", "bash", "zsh", "dash", "fish", "ksh"]);
|
|
9
|
+
const AGENTS = [[/^claude$|claude\/versions\//, "claude"], [/^codex(-.*)?$/, "codex"], [/^\.?opencode$/, "opencode"], [/^phren-agent$/, "phren agent"]];
|
|
10
|
+
/** What a process is, when it is something agents start and forget. */
|
|
11
|
+
export function classify(row, parentGone) {
|
|
12
|
+
const base = path.basename(row.command), args = row.args;
|
|
13
|
+
// `until ! pgrep -f text; do sleep 5; done`: pgrep sees this shell's own command line, so it never ends.
|
|
14
|
+
// `pgrep -x name` matches the program name only and is fine; `-f` is the one that matches itself.
|
|
15
|
+
if (SHELLS.has(base.replace(/^-/, "")) && /\b(?:until|while)\b.*\bpgrep\s+(?:-[a-zA-Z]*\s+)*-[a-zA-Z]*f/.test(args))
|
|
16
|
+
return { kind: "wait loop", name: "pgrep -f wait loop" };
|
|
17
|
+
if (/GradleDaemon|org\.gradle\.launcher\.daemon/.test(args))
|
|
18
|
+
return { kind: "build daemon", name: "Gradle daemon" };
|
|
19
|
+
if (/KotlinCompileDaemon|kotlin-daemon/.test(args))
|
|
20
|
+
return { kind: "build daemon", name: "Kotlin daemon" };
|
|
21
|
+
if (/\bturbo(?:\.exe)?\s+daemon\b/.test(args))
|
|
22
|
+
return { kind: "build daemon", name: "turbo daemon" };
|
|
23
|
+
if (/\btsc(?:\.js)?\b.*\s(?:--watch|-w)(?:\s|$)/.test(args))
|
|
24
|
+
return { kind: "build daemon", name: "tsc --watch" };
|
|
25
|
+
if (/\bvitest(?:\.mjs)?\b/.test(args) && !/\bvitest(?:\.mjs)?\s+(?:run|bench|list)\b|\s--run\b/.test(args) && !/\/vitest\/dist\/workers?\//.test(args))
|
|
26
|
+
return { kind: "test watcher", name: "vitest (watch)" };
|
|
27
|
+
if (/\bjest(?:\.js)?\b.*\s--watch(?:All)?\b/.test(args))
|
|
28
|
+
return { kind: "test watcher", name: "jest --watch" };
|
|
29
|
+
if (/\b(next|nuxt|astro|remix|storybook|wrangler)\b(?:\.m?js)?\s+dev\b/.test(args))
|
|
30
|
+
return { kind: "dev server", name: `${/\b(next|nuxt|astro|remix|storybook|wrangler)\b/.exec(args)[1]} dev` };
|
|
31
|
+
if (/\bvite(?:\.m?js)?\b(?!\s+build)/.test(args) && !/\bvitest\b/.test(args))
|
|
32
|
+
return { kind: "dev server", name: "vite" };
|
|
33
|
+
if (/webpack-dev-server|\bwebpack(?:\.js)?\s+serve\b/.test(args))
|
|
34
|
+
return { kind: "dev server", name: "webpack dev server" };
|
|
35
|
+
if (/\b(?:nodemon|tsx\s+watch)\b/.test(args))
|
|
36
|
+
return { kind: "dev server", name: /nodemon/.test(args) ? "nodemon" : "tsx watch" };
|
|
37
|
+
if (/\buvicorn\b.*--reload|\bpython3?\s+-m\s+http\.server\b|\brails\s+s(?:erver)?\b/.test(args))
|
|
38
|
+
return { kind: "dev server", name: base };
|
|
39
|
+
if (parentGone && /--headless\b/.test(args) && /chrom|firefox|headless_shell/i.test(row.command + args) && !/--type=/.test(args))
|
|
40
|
+
return { kind: "headless browser", name: "headless browser" };
|
|
41
|
+
return undefined;
|
|
42
|
+
}
|
|
43
|
+
/** The agent above a process, by ancestry or (Linux) by the session ids agents put in their children's environment. */
|
|
44
|
+
function startedBy(row, byPid, env) {
|
|
45
|
+
let current = byPid.get(row.ppid);
|
|
46
|
+
for (let depth = 0; current && depth < 24; depth++, current = byPid.get(current.ppid)) {
|
|
47
|
+
const base = path.basename(current.command);
|
|
48
|
+
const agent = AGENTS.find(([pattern]) => pattern.test(base) || pattern.test(current.command));
|
|
49
|
+
if (agent)
|
|
50
|
+
return `${agent[1]} (pid ${current.pid})`;
|
|
51
|
+
}
|
|
52
|
+
const vars = env(row.pid);
|
|
53
|
+
if (!vars)
|
|
54
|
+
return undefined;
|
|
55
|
+
const id = (name) => new RegExp(`(?:^|\\0)${name}=([^\\0]+)`).exec(vars)?.[1];
|
|
56
|
+
if (id("PHREN_FANOUT_JOB"))
|
|
57
|
+
return `fan-out worker ${id("PHREN_FANOUT_JOB")} (gone)`;
|
|
58
|
+
if (id("CLAUDE_CODE_SESSION_ID") || id("CLAUDECODE"))
|
|
59
|
+
return `claude session ${id("CLAUDE_CODE_SESSION_ID")?.slice(0, 8) ?? ""} (gone)`.replace(" ", " ");
|
|
60
|
+
if (id("CODEX_THREAD_ID") || id("CODEX_SESSION_ID"))
|
|
61
|
+
return `codex thread ${(id("CODEX_THREAD_ID") ?? id("CODEX_SESSION_ID")).slice(0, 8)} (gone)`;
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Report rows from a process table. `cpu` is each pid's cumulative CPU
|
|
66
|
+
* seconds; `samples` is what an earlier report saw, so a process whose CPU
|
|
67
|
+
* time has not moved since is idle at least that long. Returns the samples to
|
|
68
|
+
* keep for next time. Without `all`, only work an agent started (or whose
|
|
69
|
+
* parent is gone) is listed.
|
|
70
|
+
*/
|
|
71
|
+
export function reapRows(rows, options) {
|
|
72
|
+
const byPid = new Map(rows.map(row => [row.pid, row])), children = new Map();
|
|
73
|
+
for (const row of rows)
|
|
74
|
+
children.set(row.ppid, [...children.get(row.ppid) ?? [], row]);
|
|
75
|
+
const env = options.env ?? (() => undefined), samples = {}, found = [];
|
|
76
|
+
// The report's own shell and its callers are never listed: they are running this.
|
|
77
|
+
const claimed = new Set();
|
|
78
|
+
for (let pid = options.self, depth = 0; pid && pid > 1 && depth < 64; pid = byPid.get(pid)?.ppid, depth++)
|
|
79
|
+
claimed.add(pid);
|
|
80
|
+
for (const row of [...rows].sort((a, b) => a.pid - b.pid)) {
|
|
81
|
+
if (claimed.has(row.pid))
|
|
82
|
+
continue;
|
|
83
|
+
const parentGone = row.ppid <= 1 || !byPid.has(row.ppid);
|
|
84
|
+
const kind = classify(row, parentGone);
|
|
85
|
+
if (!kind)
|
|
86
|
+
continue;
|
|
87
|
+
const by = startedBy(row, byPid, env) ?? (parentGone ? "parent gone" : undefined);
|
|
88
|
+
if (!by && !options.all)
|
|
89
|
+
continue;
|
|
90
|
+
// A server's children (esbuild, workers) count toward it and are not listed again.
|
|
91
|
+
let rss = 0;
|
|
92
|
+
const stack = [row];
|
|
93
|
+
while (stack.length) {
|
|
94
|
+
const next = stack.pop();
|
|
95
|
+
claimed.add(next.pid);
|
|
96
|
+
rss += next.rssKB * 1024;
|
|
97
|
+
stack.push(...children.get(next.pid) ?? []);
|
|
98
|
+
}
|
|
99
|
+
const key = `${row.pid}:${row.startedAt ?? 0}`, cpuSeconds = options.cpu.get(row.pid);
|
|
100
|
+
let idleMs;
|
|
101
|
+
if (cpuSeconds !== undefined) {
|
|
102
|
+
const before = options.samples[key];
|
|
103
|
+
const since = before && before.cpuSeconds === cpuSeconds ? before.since : options.now;
|
|
104
|
+
samples[key] = { cpuSeconds, since };
|
|
105
|
+
if (before)
|
|
106
|
+
idleMs = options.now - since;
|
|
107
|
+
}
|
|
108
|
+
const ageMs = row.startedAt ? options.now - row.startedAt : undefined;
|
|
109
|
+
const cwd = options.cwd?.(row.pid);
|
|
110
|
+
const ancestors = [];
|
|
111
|
+
for (let up = byPid.get(row.ppid); up && ancestors.length < 64; up = byPid.get(up.ppid))
|
|
112
|
+
ancestors.push(up.pid);
|
|
113
|
+
const pane = [row.pid, ...ancestors].map(pid => options.owners?.get(pid)).find(Boolean);
|
|
114
|
+
found.push({ ...kind, pid: row.pid, ...(row.startedAt ? { startedAt: row.startedAt } : {}), ancestors, ...(pane ? { pane } : {}), ...(ageMs !== undefined ? { ageMs } : {}), ...(idleMs !== undefined ? { idleMs } : {}),
|
|
115
|
+
...(ageMs && cpuSeconds !== undefined ? { cpuShare: Math.min(1, cpuSeconds * 1000 / ageMs) } : {}),
|
|
116
|
+
rssBytes: rss, by: by ?? "you", ...(cwd ? { cwd } : {}), stop: `kill ${row.pid}` });
|
|
117
|
+
}
|
|
118
|
+
found.sort((a, b) => (b.idleMs ?? -1) - (a.idleMs ?? -1) || (b.ageMs ?? 0) - (a.ageMs ?? 0));
|
|
119
|
+
return { rows: found, samples };
|
|
120
|
+
}
|
|
121
|
+
/** `ps -o pid=,time=` cumulative CPU: `[[dd-]hh:]mm:ss[.cc]`. */
|
|
122
|
+
export function parseCpuTimes(output) {
|
|
123
|
+
const cpu = new Map();
|
|
124
|
+
for (const line of output.split("\n")) {
|
|
125
|
+
const match = /^\s*(\d+)\s+(\S+)\s*$/.exec(line);
|
|
126
|
+
const seconds = match ? parseEtime(match[2].replace(/\.\d+$/, "")) : undefined;
|
|
127
|
+
if (match && seconds !== undefined)
|
|
128
|
+
cpu.set(Number(match[1]), seconds);
|
|
129
|
+
}
|
|
130
|
+
return cpu;
|
|
131
|
+
}
|
|
132
|
+
/** Databases cloned from a test template (`hub_test_797` beside `hub_test`): name, template, size and open connections. */
|
|
133
|
+
export function testClones(rows) {
|
|
134
|
+
const names = new Set(rows.map(row => row.name));
|
|
135
|
+
return rows.flatMap(row => {
|
|
136
|
+
// Strip `_suffix` parts until another database's name is left.
|
|
137
|
+
let template = /^(.*)_[a-z0-9]+$/i.exec(row.name)?.[1];
|
|
138
|
+
while (template && !names.has(template))
|
|
139
|
+
template = /^(.*)_[a-z0-9]+$/i.exec(template)?.[1];
|
|
140
|
+
if (!template || !/test/i.test(template))
|
|
141
|
+
return [];
|
|
142
|
+
return [{ name: row.name, template, ...(row.bytes !== undefined ? { bytes: row.bytes } : {}), connections: row.connections, stop: `dropdb '${row.name.replace(/'/g, "'\\''")}'` }];
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
async function postgresClones() {
|
|
146
|
+
const sql = "select datname, pg_database_size(datname), (select count(*) from pg_stat_activity a where a.datname = d.datname) from pg_database d where not datistemplate and datallowconn";
|
|
147
|
+
try {
|
|
148
|
+
const { stdout } = await exec("psql", ["-XAtq", "-F", "\t", "-d", "postgres", "-c", sql], { timeout: 5_000, env: { ...process.env, PGCONNECT_TIMEOUT: "3" } });
|
|
149
|
+
const rows = stdout.split("\n").filter(Boolean).map(line => { const [name, bytes, connections] = line.split("\t"); return { name, bytes: Number(bytes), connections: Number(connections) || 0 }; });
|
|
150
|
+
return { databases: testClones(rows) };
|
|
151
|
+
}
|
|
152
|
+
catch (error) {
|
|
153
|
+
const code = error.code;
|
|
154
|
+
return { databases: [], note: code === "ENOENT" ? "psql not installed; Postgres not checked" : "Postgres not reachable with psql's defaults (PGHOST, PGUSER); not checked" };
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
function samplesFile() { return path.join(path.dirname(slotsRoot()), "reap-samples.json"); }
|
|
158
|
+
export async function runReap(args) {
|
|
159
|
+
if (args.some(arg => arg !== "--json" && arg !== "--all"))
|
|
160
|
+
throw new Error("Usage: phren reap [--all] [--json]");
|
|
161
|
+
const ps = (format) => exec("/bin/ps", ["-axo", format], { timeout: 5_000, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, LC_ALL: "C" } }).then(r => r.stdout);
|
|
162
|
+
const [stats, argv, elapsed, times] = await Promise.all([ps("pid=,ppid=,pgid=,pcpu=,rss=,comm="), ps("pid=,args="), ps("pid=,etime=").catch(() => ""), ps("pid=,time=").catch(() => "")]);
|
|
163
|
+
const now = Date.now(), rows = withStartTimes(parsePs(stats, argv), elapsed, now);
|
|
164
|
+
let previous = {};
|
|
165
|
+
try {
|
|
166
|
+
previous = JSON.parse(fs.readFileSync(samplesFile(), "utf8"));
|
|
167
|
+
}
|
|
168
|
+
catch { /* First report. */ }
|
|
169
|
+
const linux = process.platform === "linux";
|
|
170
|
+
const report = reapRows(rows, { now, cpu: parseCpuTimes(times), samples: previous, all: args.includes("--all"), self: process.pid,
|
|
171
|
+
env: pid => linux ? (() => { try {
|
|
172
|
+
return fs.readFileSync(`/proc/${pid}/environ`, "utf8");
|
|
173
|
+
}
|
|
174
|
+
catch {
|
|
175
|
+
return undefined;
|
|
176
|
+
} })() : undefined,
|
|
177
|
+
cwd: pid => linux ? (() => { try {
|
|
178
|
+
return fs.readlinkSync(`/proc/${pid}/cwd`);
|
|
179
|
+
}
|
|
180
|
+
catch {
|
|
181
|
+
return undefined;
|
|
182
|
+
} })() : undefined });
|
|
183
|
+
try {
|
|
184
|
+
fs.mkdirSync(path.dirname(samplesFile()), { recursive: true, mode: 0o700 });
|
|
185
|
+
fs.writeFileSync(samplesFile(), JSON.stringify(report.samples), { mode: 0o600 });
|
|
186
|
+
}
|
|
187
|
+
catch { /* Idle times start over next time. */ }
|
|
188
|
+
const pg = await postgresClones();
|
|
189
|
+
if (args.includes("--json")) {
|
|
190
|
+
console.log(JSON.stringify({ processes: report.rows, databases: pg.databases, ...(pg.note ? { note: pg.note } : {}) }, null, 2));
|
|
191
|
+
return 0;
|
|
192
|
+
}
|
|
193
|
+
const mb = (bytes) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(bytes / 1024 ** 2)} MB`;
|
|
194
|
+
if (!report.rows.length && !pg.databases.length)
|
|
195
|
+
console.log("Nothing left running by agents.");
|
|
196
|
+
for (const row of report.rows) {
|
|
197
|
+
const idle = row.idleMs !== undefined ? `idle ${minutes(row.idleMs)}` : `idle unknown${row.cpuShare !== undefined ? `, ${(row.cpuShare * 100).toFixed(1)}% CPU over its life` : ""}`;
|
|
198
|
+
console.log(`${row.kind}: ${row.name}, pid ${row.pid}, ${row.ageMs !== undefined ? `up ${minutes(row.ageMs)}` : "age unknown"}, ${idle}, ${mb(row.rssBytes)}, started by ${row.by}${row.cwd ? `, in ${row.cwd}` : ""}`);
|
|
199
|
+
console.log(` stop: ${row.stop}`);
|
|
200
|
+
}
|
|
201
|
+
for (const db of pg.databases) {
|
|
202
|
+
console.log(`test database: ${db.name} (clone of ${db.template})${db.bytes !== undefined ? `, ${mb(db.bytes)}` : ""}, ${db.connections} connection${db.connections === 1 ? "" : "s"}`);
|
|
203
|
+
console.log(` stop: ${db.stop}`);
|
|
204
|
+
}
|
|
205
|
+
if (pg.note)
|
|
206
|
+
console.log(pg.note);
|
|
207
|
+
if (report.rows.some(row => row.idleMs === undefined))
|
|
208
|
+
console.log("Idle time shows from the second report on: run phren reap again later.");
|
|
209
|
+
console.log("Nothing was stopped. Run the stop commands you want.");
|
|
210
|
+
return 0;
|
|
211
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type Budget, type Pressure } from "./budget.js";
|
|
2
|
+
/**
|
|
3
|
+
* A computer-wide counting semaphore in a directory: one small JSON ticket per
|
|
4
|
+
* waiting or running job, ordered by priority and then arrival. Any shell on
|
|
5
|
+
* the computer joins it through `phren heavy`, and `phren fanout run` through
|
|
6
|
+
* its `workers` pool, so agents in different panes, harnesses and stores share
|
|
7
|
+
* one count. A ticket whose process is gone is dropped by the next reader, so
|
|
8
|
+
* a killed job never holds its slot.
|
|
9
|
+
*/
|
|
10
|
+
export declare const PRIORITIES: {
|
|
11
|
+
readonly release: 2;
|
|
12
|
+
readonly normal: 1;
|
|
13
|
+
readonly low: 0;
|
|
14
|
+
};
|
|
15
|
+
export type PriorityName = keyof typeof PRIORITIES;
|
|
16
|
+
export interface Ticket {
|
|
17
|
+
id: string;
|
|
18
|
+
pid: number;
|
|
19
|
+
priority: number;
|
|
20
|
+
createdAt: number;
|
|
21
|
+
label: string;
|
|
22
|
+
state: "waiting" | "running";
|
|
23
|
+
startedAt?: number;
|
|
24
|
+
}
|
|
25
|
+
export declare function slotsRoot(env?: NodeJS.ProcessEnv): string;
|
|
26
|
+
export declare function priorityName(priority: number): PriorityName;
|
|
27
|
+
/** Tickets of a pool, with dead holders' and waiters' tickets removed. */
|
|
28
|
+
export declare function readTickets(dir: string, isAlive?: (pid: number) => boolean): Ticket[];
|
|
29
|
+
/** Waiters in the order they will start: release work first, then by arrival. */
|
|
30
|
+
export declare function queueOrder(tickets: readonly Ticket[]): Ticket[];
|
|
31
|
+
export declare function minutes(ms: number): string;
|
|
32
|
+
export interface AcquireOptions {
|
|
33
|
+
pool: string;
|
|
34
|
+
slots: number;
|
|
35
|
+
priority: number;
|
|
36
|
+
label: string;
|
|
37
|
+
budget: Budget;
|
|
38
|
+
pressure: () => Promise<Pressure | undefined>;
|
|
39
|
+
/** Called each time the reason for waiting changes, and once on start. */
|
|
40
|
+
report: (message: string) => void;
|
|
41
|
+
pollMs?: number;
|
|
42
|
+
timeoutMs?: number;
|
|
43
|
+
root?: string;
|
|
44
|
+
pid?: number;
|
|
45
|
+
now?: () => number;
|
|
46
|
+
sleep?: (ms: number) => Promise<void>;
|
|
47
|
+
}
|
|
48
|
+
export interface Held {
|
|
49
|
+
id: string;
|
|
50
|
+
release: () => void;
|
|
51
|
+
waitedMs: number;
|
|
52
|
+
}
|
|
53
|
+
/** Waits for a slot. Throws `QueueTimeout` after `timeoutMs`; the ticket is removed either way. */
|
|
54
|
+
export declare function acquire(options: AcquireOptions): Promise<Held>;
|
|
55
|
+
export declare class QueueTimeout extends Error {
|
|
56
|
+
}
|
|
57
|
+
export declare function poolStatus(pool: string, root?: string): Ticket[];
|
|
58
|
+
export declare function pools(root?: string): string[];
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import { randomBytes } from "node:crypto";
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import * as path from "node:path";
|
|
5
|
+
import { withFileLock } from "../governance/locks.js";
|
|
6
|
+
import { pressureReason } from "./budget.js";
|
|
7
|
+
/**
|
|
8
|
+
* A computer-wide counting semaphore in a directory: one small JSON ticket per
|
|
9
|
+
* waiting or running job, ordered by priority and then arrival. Any shell on
|
|
10
|
+
* the computer joins it through `phren heavy`, and `phren fanout run` through
|
|
11
|
+
* its `workers` pool, so agents in different panes, harnesses and stores share
|
|
12
|
+
* one count. A ticket whose process is gone is dropped by the next reader, so
|
|
13
|
+
* a killed job never holds its slot.
|
|
14
|
+
*/
|
|
15
|
+
export const PRIORITIES = { release: 2, normal: 1, low: 0 };
|
|
16
|
+
export function slotsRoot(env = process.env) {
|
|
17
|
+
return env.PHREN_SLOTS_DIR || path.join(env.XDG_STATE_HOME || path.join(homedir(), ".local", "state"), "phren", "slots");
|
|
18
|
+
}
|
|
19
|
+
function alive(pid) {
|
|
20
|
+
try {
|
|
21
|
+
process.kill(pid, 0);
|
|
22
|
+
return true;
|
|
23
|
+
}
|
|
24
|
+
catch (error) {
|
|
25
|
+
return error.code === "EPERM";
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
export function priorityName(priority) {
|
|
29
|
+
return Object.keys(PRIORITIES).find(name => PRIORITIES[name] === priority) ?? "normal";
|
|
30
|
+
}
|
|
31
|
+
/** Tickets of a pool, with dead holders' and waiters' tickets removed. */
|
|
32
|
+
export function readTickets(dir, isAlive = alive) {
|
|
33
|
+
let names;
|
|
34
|
+
try {
|
|
35
|
+
names = fs.readdirSync(dir);
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
return [];
|
|
39
|
+
}
|
|
40
|
+
const tickets = [];
|
|
41
|
+
for (const name of names.filter(n => n.endsWith(".json"))) {
|
|
42
|
+
const file = path.join(dir, name);
|
|
43
|
+
try {
|
|
44
|
+
const ticket = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
45
|
+
if (!Number.isInteger(ticket.pid) || !isAlive(ticket.pid)) {
|
|
46
|
+
fs.rmSync(file, { force: true });
|
|
47
|
+
continue;
|
|
48
|
+
}
|
|
49
|
+
tickets.push(ticket);
|
|
50
|
+
}
|
|
51
|
+
catch { /* Partly written or removed meanwhile. */ }
|
|
52
|
+
}
|
|
53
|
+
return tickets;
|
|
54
|
+
}
|
|
55
|
+
/** Waiters in the order they will start: release work first, then by arrival. */
|
|
56
|
+
export function queueOrder(tickets) {
|
|
57
|
+
return tickets.filter(t => t.state === "waiting").sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt || a.id.localeCompare(b.id));
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Whether ticket `id` may start now. The pressure gate holds only while
|
|
61
|
+
* another job in the pool runs: with the pool empty the first job always
|
|
62
|
+
* starts (with a warning), so pressure from outside the pool can slow work
|
|
63
|
+
* but never stop it for good.
|
|
64
|
+
*/
|
|
65
|
+
function decide(tickets, id, slots, pressure, budget, now = Date.now()) {
|
|
66
|
+
const running = tickets.filter(t => t.state === "running");
|
|
67
|
+
const order = queueOrder(tickets), position = order.findIndex(t => t.id === id);
|
|
68
|
+
const busy = running.map(t => `${t.label} (pid ${t.pid}, ${minutes(now - (t.startedAt ?? t.createdAt))})`).join(", ");
|
|
69
|
+
if (running.length >= slots)
|
|
70
|
+
return { start: false, reason: `all ${slots} slot${slots === 1 ? "" : "s"} busy: ${busy}` };
|
|
71
|
+
if (position > 0)
|
|
72
|
+
return { start: false, reason: `${position} job${position === 1 ? "" : "s"} ahead (${order.slice(0, position).map(t => `${t.label}, ${priorityName(t.priority)}`).join("; ")})` };
|
|
73
|
+
const pressed = pressure && pressureReason(pressure, budget);
|
|
74
|
+
if (pressed && running.length)
|
|
75
|
+
return { start: false, reason: `${pressed}; ${running.length} running: ${busy}` };
|
|
76
|
+
return pressed ? { start: true, warning: `${pressed}; starting anyway because nothing else in this pool is running` } : { start: true };
|
|
77
|
+
}
|
|
78
|
+
export function minutes(ms) {
|
|
79
|
+
if (ms < 60_000)
|
|
80
|
+
return `${Math.max(0, Math.round(ms / 1000))}s`;
|
|
81
|
+
const m = Math.round(ms / 60_000);
|
|
82
|
+
return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h ${m % 60}m`;
|
|
83
|
+
}
|
|
84
|
+
/** Waits for a slot. Throws `QueueTimeout` after `timeoutMs`; the ticket is removed either way. */
|
|
85
|
+
export async function acquire(options) {
|
|
86
|
+
if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(options.pool))
|
|
87
|
+
throw new Error("Pool names are lowercase letters, digits and dashes.");
|
|
88
|
+
const dir = path.join(options.root ?? slotsRoot(), options.pool), now = options.now ?? Date.now;
|
|
89
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
90
|
+
const id = `${now()}-${randomBytes(6).toString("hex")}`, file = path.join(dir, `${id}.json`), began = now();
|
|
91
|
+
const ticket = { id, pid: options.pid ?? process.pid, priority: options.priority, createdAt: began, label: options.label.slice(0, 120), state: "waiting" };
|
|
92
|
+
const write = () => { const tmp = `${file}.tmp`; fs.writeFileSync(tmp, JSON.stringify(ticket), { mode: 0o600 }); fs.renameSync(tmp, file); };
|
|
93
|
+
const release = () => { fs.rmSync(file, { force: true }); };
|
|
94
|
+
write();
|
|
95
|
+
const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
|
|
96
|
+
let said = "";
|
|
97
|
+
try {
|
|
98
|
+
for (;;) {
|
|
99
|
+
const pressure = await options.pressure().catch(() => undefined);
|
|
100
|
+
const decision = withFileLock(path.join(dir, ".queue"), () => {
|
|
101
|
+
const result = decide(readTickets(dir), id, options.slots, pressure, options.budget, now());
|
|
102
|
+
if (result.start) {
|
|
103
|
+
ticket.state = "running";
|
|
104
|
+
ticket.startedAt = now();
|
|
105
|
+
write();
|
|
106
|
+
}
|
|
107
|
+
return result;
|
|
108
|
+
});
|
|
109
|
+
if (decision.start) {
|
|
110
|
+
const waited = now() - began;
|
|
111
|
+
options.report(`${decision.warning ? `warning: ${decision.warning}. ` : ""}started${waited >= 1_000 ? ` after waiting ${minutes(waited)}` : ""}`);
|
|
112
|
+
return { id, release, waitedMs: waited };
|
|
113
|
+
}
|
|
114
|
+
if (decision.reason !== said) {
|
|
115
|
+
said = decision.reason;
|
|
116
|
+
options.report(`queued: ${decision.reason}`);
|
|
117
|
+
}
|
|
118
|
+
if (options.timeoutMs !== undefined && now() - began >= options.timeoutMs)
|
|
119
|
+
throw new QueueTimeout(`gave up after ${minutes(now() - began)} in the queue: ${said}`);
|
|
120
|
+
await sleep(options.pollMs ?? 5_000);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
catch (error) {
|
|
124
|
+
release();
|
|
125
|
+
throw error;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
export class QueueTimeout extends Error {
|
|
129
|
+
}
|
|
130
|
+
export function poolStatus(pool, root = slotsRoot()) {
|
|
131
|
+
const dir = path.join(root, pool);
|
|
132
|
+
const tickets = readTickets(dir);
|
|
133
|
+
return [...tickets.filter(t => t.state === "running").sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0)), ...queueOrder(tickets)];
|
|
134
|
+
}
|
|
135
|
+
export function pools(root = slotsRoot()) {
|
|
136
|
+
try {
|
|
137
|
+
return fs.readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort();
|
|
138
|
+
}
|
|
139
|
+
catch {
|
|
140
|
+
return [];
|
|
141
|
+
}
|
|
142
|
+
}
|
package/dist/modules/registry.js
CHANGED
|
@@ -26,7 +26,7 @@ export const BUILTIN_MODULES = [
|
|
|
26
26
|
]),
|
|
27
27
|
],
|
|
28
28
|
cliCommands: [
|
|
29
|
-
"init", "quickstart", "add", "agent", "projects", "search", "status", "doctor", "web-ui", "graph", "shell",
|
|
29
|
+
"init", "quickstart", "add", "agent", "projects", "search", "status", "doctor", "web-ui", "graph", "shell", "heavy", "reap",
|
|
30
30
|
"add-finding", "pin", "review", "session-context", "sessions", "finding", "note", "notes",
|
|
31
31
|
"search-fragments", "related-docs", "truths", "promote", "skills", "detect-skills", "hooks", "config",
|
|
32
32
|
"maintain", "dream", "consolidation-status", "quality-feedback", "mcp-mode", "hooks-mode", "preset", "snippet",
|
|
@@ -70,7 +70,7 @@ export const BUILTIN_MODULES = [
|
|
|
70
70
|
cliCommands: [
|
|
71
71
|
"bridge", "bridge install", "bridge update", "bridge uninstall", "bridge rollback", "bridge status",
|
|
72
72
|
"browser", "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh", "pair", "unpair",
|
|
73
|
-
"bridge fanouts archive", "bridge accounts", "bridge askpass", "canary", "computers", "computers mcp", "usage", "sudo", "secret-exec",
|
|
73
|
+
"bridge fanouts archive", "bridge accounts", "bridge askpass", "canary", "computers", "computers mcp", "housekeeping", "usage", "sudo", "secret-exec",
|
|
74
74
|
],
|
|
75
75
|
agentHooks: [
|
|
76
76
|
{ agents: ["codex"], events: ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest"], handler: "bridge-hook.mjs hook codex" },
|
|
@@ -84,12 +84,13 @@ export const BUILTIN_MODULES = [
|
|
|
84
84
|
...routes("GET", [
|
|
85
85
|
"/v1/health", "/v1/health/details", "/v1/health/peers", "/v1/muxes", "/v1/terminals/resolve", "/v1/activity", "/v1/metrics", "/v1/web-servers", "/v1/simulators", "/v1/browsers", "/v1/browsers/recordings", "/v1/browsers/recordings/index", "/v1/browsers/recordings/frame",
|
|
86
86
|
"/v1/simulators/screenshot", "/v1/simulators/apps", "/v1/files", "/v1/models", "/v1/harnesses", "/v1/projects/files",
|
|
87
|
-
"/v1/uploads/image", "/v1/files/range", "/v1/files/resolve", "/v1/usage", "/v1/resources", "/v1/speech/voices", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
|
|
87
|
+
"/v1/uploads/image", "/v1/files/range", "/v1/files/resolve", "/v1/usage", "/v1/resources", "/v1/housekeeping", "/v1/speech/voices", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
|
|
88
88
|
"/v1/workspaces", "/v1/workspaces/panes", "/v1/workspaces/layout", "/v1/transcripts/blob", "/v1/transcripts/history", "/v1/sudo", "/v1/secrets",
|
|
89
89
|
"/v1/conversations/search",
|
|
90
90
|
"/v1/subagents", "/v1/subagents/transcript", "/v1/subagents/messages", "/v1/sessions/move", "/v1/sessions/moves", "/v1/sessions/move/computers", "/v1/sessions/move/availability", "/v1/sessions/move/intent", "/v1/sessions/move/launch", "/v1/dispatch/relocation", "/v1/dispatch/arrival",
|
|
91
91
|
]),
|
|
92
92
|
...routes("POST", [
|
|
93
|
+
"/v1/housekeeping/approve", "/v1/housekeeping/dismiss", "/v1/housekeeping/restore", "/v1/housekeeping/scan",
|
|
93
94
|
"/v1/push/register", "/v1/push/forget", "/v1/push/answer", "/v1/push/target", "/v1/push/presence", "/v1/files", "/v1/files/delete", "/v1/projects/add", "/v1/simulators/action",
|
|
94
95
|
"/v1/workspaces/launch", "/v1/workspaces/create", "/v1/workspaces/focus", "/v1/workspaces/rename",
|
|
95
96
|
"/v1/workspaces/close", "/v1/sessions/rename", "/v1/sessions/seen", "/v1/sessions/move", "/v1/accounts/claude/add", "/v1/accounts/claude/settings", "/v1/accounts/allowed-pools", "/v1/sessions/move/abort", "/v1/sessions/move/launch", "/v1/prompt", "/v1/prompt/status", "/v1/prompt/after-turn", "/v1/prompt/after-turn/list", "/v1/prompt/after-turn/edit", "/v1/prompt/after-turn/cancel", "/v1/prompt/queue", "/v1/model", "/v1/settings", "/v1/agents/permission-mode", "/v1/side-question/dismiss", "/v1/keys", "/v1/secret", "/v1/upload",
|
package/package.json
CHANGED
|
@@ -104,6 +104,16 @@ A worker that needs root runs `sudo -A <command>`: its launch sets
|
|
|
104
104
|
`SUDO_ASKPASS`, and the owner approves the exact command and types the
|
|
105
105
|
password on the phone. Plain `sudo` fails without a terminal.
|
|
106
106
|
|
|
107
|
+
Each computer has a budget for agent work (`~/.config/phren/budget.yaml`):
|
|
108
|
+
workers launched with `phren fanout run` queue past it, `dispatch` to
|
|
109
|
+
`anywhere` passes over a computer whose memory or load is over it (the
|
|
110
|
+
receipt's `skipped` says so), and an agent that names such a computer gets
|
|
111
|
+
`over_budget`. Have every worker run full test suites and native builds as
|
|
112
|
+
`phren heavy -- <command>` (`--priority release` for release work) instead of
|
|
113
|
+
its own lock, stop the servers and daemons it started before it reports, and
|
|
114
|
+
never wait with a `pgrep -f` loop, which matches itself. `phren reap` lists
|
|
115
|
+
what agents left running with the command to stop each; it stops nothing.
|
|
116
|
+
|
|
107
117
|
You are the one conductor for this computer and every computer linked with
|
|
108
118
|
it; a second conductor in the group is refused at launch. Conductors on
|
|
109
119
|
computers that are not linked share only the store, so claim a task before you
|
|
@@ -27,3 +27,33 @@ to send a bounded follow-up, and `phren fanout review JOB` for a review round.
|
|
|
27
27
|
Codex resumes inherit their original sandbox; ask a resumed author to review
|
|
28
28
|
without edits. Use a fresh review-tier worker for an enforced read-only sandbox.
|
|
29
29
|
Archive completed jobs with `phren fanout archive`.
|
|
30
|
+
|
|
31
|
+
## Sharing one computer
|
|
32
|
+
|
|
33
|
+
Workers share the computer's memory, CPU, git state and processes with every
|
|
34
|
+
other agent on it. On a 31 GB Linux box, 5 to 10 agents with full test runs
|
|
35
|
+
ran it out of memory three times in a day.
|
|
36
|
+
|
|
37
|
+
- `phren fanout run` waits for this computer's worker budget (about one worker
|
|
38
|
+
per 7 GB, set in `~/.config/phren/budget.yaml`) and says on stderr when it
|
|
39
|
+
queued and why. `--priority release` goes first; `--wait 0` fails at once.
|
|
40
|
+
- Run every heavy job (a full test suite, a Gradle or Xcode build) as
|
|
41
|
+
`phren heavy -- <command>`, with `--priority release` for release work. It
|
|
42
|
+
allows N at once (about one per 12 GB) and replaces any lock of your own.
|
|
43
|
+
`phren heavy status` shows who runs and who waits.
|
|
44
|
+
- Stop what you started before you finish: dev servers, watchers, browsers,
|
|
45
|
+
build daemons (`./gradlew --stop`) and test database clones (`dropdb`).
|
|
46
|
+
`phren reap` lists what agents left running with the command that stops
|
|
47
|
+
each; it stops nothing, and the owner says which to stop.
|
|
48
|
+
- Never wait with `until ! pgrep -f <text>`: `pgrep -f` matches the waiting
|
|
49
|
+
shell's own command line, so the loop never ends (26 were found running
|
|
50
|
+
hours after their agents finished). Wait on a PID or a file, with a
|
|
51
|
+
deadline: `for i in $(seq 360); do kill -0 "$pid" 2>/dev/null || break; sleep 5; done`,
|
|
52
|
+
or poll the job's `exit.txt`.
|
|
53
|
+
- Commit in small steps, each one building, so a usage-limit stop loses
|
|
54
|
+
nothing that is not in a commit.
|
|
55
|
+
- `git stash` and the rerere cache belong to the repository, not the
|
|
56
|
+
worktree: every worktree sees the same stash list and replays the same
|
|
57
|
+
recorded resolutions. Never `git stash pop` (one agent's pop applied
|
|
58
|
+
another session's old stash); commit work in progress on your own branch
|
|
59
|
+
instead. After a merge that rerere resolved, read the diff before you commit.
|