aegiscode 6.5.8 → 6.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,534 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * queue.js — the autonomous work queue.
5
+ *
6
+ * "Do X autonomously" means: nobody is at the keyboard, so the task has to
7
+ * survive the conversation that produced it. This module is that survival: a
8
+ * durable, crash-safe list of tasks in
9
+ * `~/.aegiscode/queue.jsonl` (`$AEGISCODE_HOME`/`$AEGIS_HOME` override the dir,
10
+ * `$AEGIS_QUEUE_FILE` the file) that any host — the desktop app, the
11
+ * `aegiscode` CLI, a systemd timer — can add to, and that a worker drains one
12
+ * task at a time.
13
+ *
14
+ * Why a FILE and not the renderer's in-memory state: the same reason the
15
+ * session store exists. The desktop app owns the queue while it is open, but a
16
+ * task queued at 18:00 has to still be there at 08:00 after a reboot, and the
17
+ * CLI has to see the tasks the GUI queued. A process-local list answers
18
+ * neither, so the queue is the file and every host is just a reader/writer of
19
+ * it.
20
+ *
21
+ * Three properties are load-bearing, and each one exists because its absence
22
+ * was a real failure:
23
+ *
24
+ * 1. WRITES ARE ATOMIC (temp file + rename). A queue that is rewritten in
25
+ * place loses everything on a crash mid-write — the same defect the session
26
+ * store was fixed for. Rename is atomic within a filesystem, so a reader
27
+ * sees either the old queue or the new one, never half of each.
28
+ *
29
+ * 2. WRITES ARE AN UPSERT keyed on id, never a blind overwrite of the whole
30
+ * file. A drain holds the queue in memory for minutes at a time, and
31
+ * anything added during that window (another host, another window, the
32
+ * queue's own `reconcile`) would be silently erased by the stale copy the
33
+ * drain saves back. The drain only ever writes back *its own* item's status
34
+ * (`settle`), and `upsert` merges instead of replacing, so a mid-drain add
35
+ * survives.
36
+ *
37
+ * 3. A `running` ITEM WHOSE PROCESS IS GONE IS `pending` AGAIN. A task is
38
+ * marked running with the pid holding it; when a worker is killed
39
+ * (SIGKILL, a reboot, a closed laptop) nothing gets to clear that flag, and
40
+ * a queue that trusts the flag is a queue that never runs that task again.
41
+ * `recoverStale` re-reads liveness instead of trusting the file, the same
42
+ * no-staleness-window pattern the worktree and session locks use.
43
+ *
44
+ * Pure-ish on purpose: every function takes its paths/clock/env from the
45
+ * caller (or a `process.env` default), so the whole module is testable against
46
+ * a temp dir with no Electron, no network, and no home directory.
47
+ */
48
+
49
+ const fs = require('node:fs');
50
+ const os = require('node:os');
51
+ const path = require('node:path');
52
+
53
+ /** The only legal statuses. `error` (not "failed") matches the runs log's. */
54
+ const STATUSES = Object.freeze(['pending', 'running', 'done', 'error']);
55
+
56
+ /**
57
+ * The per-user data dir the whole repo already agrees on: `$AEGISCODE_HOME`
58
+ * (this plugin's convention — see worktree-lock.js's worktreeLockDir and
59
+ * config.js's aegisDir) or `~/.aegiscode`. `$AEGIS_HOME` is honoured as well so
60
+ * a host that already exports it (the generic spelling) points at the same
61
+ * place rather than quietly queueing into a second directory — two hosts
62
+ * disagreeing about where the queue file goes is indistinguishable from having
63
+ * no queue.
64
+ */
65
+ function dataDir(env = process.env) {
66
+ const e = env || {};
67
+ const home = e.AEGISCODE_HOME || e.AEGIS_HOME;
68
+ return home ? path.resolve(home) : path.join(os.homedir(), '.aegiscode');
69
+ }
70
+
71
+ /** The queue file for this environment (tests point AEGIS_QUEUE_FILE at a temp dir). */
72
+ function queuePath(env = process.env) {
73
+ return (env && env.AEGIS_QUEUE_FILE) || path.join(dataDir(env), 'queue.jsonl');
74
+ }
75
+
76
+ /** Append-only accounting: one line per finished task, never rewritten. */
77
+ function runsPath(env = process.env) {
78
+ return (env && env.AEGIS_RUNS_FILE) || path.join(dataDir(env), 'runs.jsonl');
79
+ }
80
+
81
+ /** The single-worker lock. One drain at a time; a second worker backs off. */
82
+ function lockPath(env = process.env) {
83
+ return (env && env.AEGIS_QUEUE_LOCK) || path.join(dataDir(env), 'queue.lock');
84
+ }
85
+
86
+ function ensureDir(dir) {
87
+ fs.mkdirSync(dir, { recursive: true });
88
+ return dir;
89
+ }
90
+
91
+ // ── reading and writing ─────────────────────────────────────────────────────
92
+
93
+ /**
94
+ * Parse a queue file. A line that does not parse is skipped rather than
95
+ * thrown on: an interrupted append (power loss between `write` and `fsync`)
96
+ * can leave a torn final line, and losing the whole queue to one bad byte is
97
+ * a worse outcome than losing the one item that was mid-write.
98
+ */
99
+ function readQueue(file) {
100
+ let raw = '';
101
+ try {
102
+ raw = fs.readFileSync(file, 'utf8');
103
+ } catch {
104
+ return []; // no queue yet is the normal first-run state, not an error
105
+ }
106
+ const out = [];
107
+ for (const line of raw.split('\n')) {
108
+ const text = line.trim();
109
+ if (!text) continue;
110
+ try {
111
+ const item = JSON.parse(text);
112
+ if (item && typeof item === 'object' && item.id != null) out.push(item);
113
+ } catch {
114
+ /* torn or hand-edited line — skip it, keep the rest */
115
+ }
116
+ }
117
+ return out;
118
+ }
119
+
120
+ /** Write the whole queue atomically (temp file + rename), mode 0600. */
121
+ function writeQueue(file, items) {
122
+ ensureDir(path.dirname(file));
123
+ const body = items.map((i) => JSON.stringify(i)).join('\n') + (items.length ? '\n' : '');
124
+ const tmp = `${file}.${process.pid}.tmp`;
125
+ fs.writeFileSync(tmp, body, { mode: 0o600 });
126
+ fs.renameSync(tmp, file);
127
+ return items;
128
+ }
129
+
130
+ function loadQueue(env = process.env) {
131
+ return readQueue(queuePath(env));
132
+ }
133
+
134
+ function saveQueue(env, items) {
135
+ return writeQueue(queuePath(env), items);
136
+ }
137
+
138
+ /**
139
+ * Highest id in the queue, +1. Ids increase for as long as the queue file has
140
+ * any history to count, so they are never reused while anything remains. They
141
+ * are NOT globally unique across generations: `clear --all` empties the file and
142
+ * the next `add` starts again at #1. The runs log therefore records each task's
143
+ * text and time alongside its id — a `#7` is unique within one queue generation,
144
+ * and the text is what makes it identifiable across a `clear --all`.
145
+ */
146
+ function nextId(items) {
147
+ let max = 0;
148
+ for (const i of items) {
149
+ const n = Number(i && i.id);
150
+ if (Number.isFinite(n) && n > max) max = n;
151
+ }
152
+ return max + 1;
153
+ }
154
+
155
+ /**
156
+ * Insert or replace by id, leaving every other item in the list untouched.
157
+ *
158
+ * This is the ONLY way a drain writes back — `saveQueue(env, upsert(loadQueue(env),
159
+ * myItem))` — and the load has to be FRESH, taken immediately before the write.
160
+ * upsert can only preserve what the caller actually passed it: hand it a stale
161
+ * snapshot and anything added since is erased, because `saveQueue` rewrites the
162
+ * whole file. The worker re-reads before each of its two writes for exactly this
163
+ * reason (autonomous.js: claim and settle). The remaining window is the instant
164
+ * between that read and the write, which is why `add` never takes the drain lock
165
+ * and a queue is a work list, not a ledger.
166
+ */
167
+ function upsert(items, entry) {
168
+ const list = Array.isArray(items) ? items : [];
169
+ const idx = list.findIndex((i) => i && i.id === entry.id);
170
+ if (idx === -1) list.push(entry);
171
+ else list[idx] = { ...list[idx], ...entry };
172
+ return list;
173
+ }
174
+
175
+ // ── the queue's own vocabulary ──────────────────────────────────────────────
176
+
177
+ /**
178
+ * Queue a task. `cwd` is where the work happens (the worker runs the turn
179
+ * with it as the tool loop's working directory), `model` is the AEGIS Cloud
180
+ * model id to run it on, and `commit` asks the worker to commit what the task
181
+ * changed (scoped — see autonomous.js).
182
+ */
183
+ function addTask(env, opts = {}) {
184
+ const task = String(opts.task == null ? '' : opts.task).trim();
185
+ if (!task) throw new Error('queue: a task needs text');
186
+ const items = loadQueue(env);
187
+ const now = opts.now || Date.now();
188
+ const entry = {
189
+ id: nextId(items),
190
+ task,
191
+ cwd: opts.cwd || process.cwd(),
192
+ model: opts.model || null,
193
+ effort: opts.effort || null,
194
+ workers: Number.isInteger(opts.workers) ? opts.workers : null,
195
+ singlePass: Boolean(opts.singlePass),
196
+ commit: Boolean(opts.commit),
197
+ maxRounds: Number.isInteger(opts.maxRounds) ? opts.maxRounds : null,
198
+ source: opts.source || 'manual',
199
+ status: 'pending',
200
+ attempts: 0,
201
+ created: now,
202
+ updated: now,
203
+ };
204
+ upsert(items, entry);
205
+ saveQueue(env, items);
206
+ return entry;
207
+ }
208
+
209
+ function findTask(items, id) {
210
+ const n = Number(id);
211
+ return (items || []).find((i) => Number(i && i.id) === n) || null;
212
+ }
213
+
214
+ /** Claim a task: `pending` → `running`, stamped with the pid that owns it. */
215
+ function markRunning(items, id, opts = {}) {
216
+ const item = findTask(items, id);
217
+ if (!item) return null;
218
+ const now = opts.now || Date.now();
219
+ item.status = 'running';
220
+ item.pid = opts.pid || process.pid;
221
+ item.startedAt = now;
222
+ item.updated = now;
223
+ item.attempts = (Number(item.attempts) || 0) + 1;
224
+ return item;
225
+ }
226
+
227
+ /**
228
+ * Record a finished task. `result` is whatever the worker learned (output
229
+ * text, token usage, round count, the commit it made); it is kept verbatim so
230
+ * the runs log and the queue never disagree about what happened.
231
+ */
232
+ function settle(items, id, { status, result, error, now = Date.now() } = {}) {
233
+ const item = findTask(items, id);
234
+ if (!item) return null;
235
+ item.status = STATUSES.includes(status) ? status : 'error';
236
+ item.updated = now;
237
+ item.finishedAt = now;
238
+ delete item.pid;
239
+ if (result !== undefined) item.result = result;
240
+ if (error) item.error = String(error);
241
+ else delete item.error;
242
+ return item;
243
+ }
244
+
245
+ /** Put a task back at the head of the queue, keeping its attempt count. */
246
+ function retryTask(env, id, opts = {}) {
247
+ const items = loadQueue(env);
248
+ const item = findTask(items, id);
249
+ if (!item) return null;
250
+ item.status = 'pending';
251
+ item.updated = opts.now || Date.now();
252
+ delete item.error;
253
+ delete item.pid;
254
+ saveQueue(env, items);
255
+ return item;
256
+ }
257
+
258
+ /**
259
+ * Drop finished items. Pending and running are NEVER removed: `clear` is the
260
+ * "tidy the log" command, and a user who runs it mid-drain must not lose the
261
+ * task that is running or the ones waiting. `all: true` (`--all`) is the
262
+ * explicit "empty it" escape hatch.
263
+ */
264
+ function clearQueue(env, { all = false } = {}) {
265
+ const items = loadQueue(env);
266
+ const kept = all ? [] : items.filter((i) => i.status === 'pending' || i.status === 'running');
267
+ const removed = items.length - kept.length;
268
+ saveQueue(env, kept);
269
+ return { removed, kept: kept.length };
270
+ }
271
+
272
+ /** True if `pid` names a live process (EPERM means it exists but isn't ours). */
273
+ function isAlive(pid) {
274
+ const n = Number(pid);
275
+ if (!Number.isInteger(n) || n <= 0) return false;
276
+ try {
277
+ process.kill(n, 0);
278
+ return true;
279
+ } catch (e) {
280
+ return Boolean(e && e.code === 'EPERM');
281
+ }
282
+ }
283
+
284
+ /**
285
+ * Re-read liveness for every `running` item. A running item whose pid is gone
286
+ * (or which never recorded one) goes back to `pending`; the queue's promise is
287
+ * that a task is worked eventually, and "a dead process left the flag up" is
288
+ * not an acceptable reason for it never to be.
289
+ *
290
+ * Items held by a LIVE pid are left alone — that process is the drain, and
291
+ * re-pending its item would run it twice.
292
+ */
293
+ function recoverStale(items, { isAliveFn = isAlive, now = Date.now() } = {}) {
294
+ const recovered = [];
295
+ for (const item of items || []) {
296
+ if (!item || item.status !== 'running') continue;
297
+ if (item.pid && isAliveFn(item.pid)) continue;
298
+ item.status = 'pending';
299
+ item.updated = now;
300
+ item.recoveredAt = now;
301
+ delete item.pid;
302
+ recovered.push(item.id);
303
+ }
304
+ return recovered;
305
+ }
306
+
307
+ /** Count of tasks a drain still has to work. */
308
+ function pendingCount(items) {
309
+ return (items || []).filter((i) => i && i.status === 'pending').length;
310
+ }
311
+
312
+ /** Pending tasks in queue order (the order they were added). */
313
+ function pending(items) {
314
+ return (items || []).filter((i) => i && i.status === 'pending');
315
+ }
316
+
317
+ // ── single-worker lock ──────────────────────────────────────────────────────
318
+
319
+ function lockHolder(env = process.env) {
320
+ try {
321
+ return JSON.parse(fs.readFileSync(lockPath(env), 'utf8'));
322
+ } catch {
323
+ return null;
324
+ }
325
+ }
326
+
327
+ /**
328
+ * Take the drain lock, or report who holds it.
329
+ *
330
+ * Only ONE drain may run at a time. Two drains are not twice as fast: they
331
+ * share a working tree, and the second one's `git add`/commit races the
332
+ * first's — the exact multi-agent-one-checkout failure the worktree lock
333
+ * exists for. The lock is a marker with a pid in it, not a timeout, so a
334
+ * worker killed with SIGKILL is reclaimed by the next caller immediately
335
+ * rather than after a staleness window nobody can tune correctly.
336
+ */
337
+ function acquireLock(env = process.env, { pid = process.pid, now = Date.now(), isAliveFn = isAlive } = {}) {
338
+ const file = lockPath(env);
339
+ const holder = lockHolder(env);
340
+ if (holder && holder.pid && holder.pid !== pid && isAliveFn(holder.pid)) {
341
+ return { ok: false, holder };
342
+ }
343
+ ensureDir(path.dirname(file));
344
+ fs.writeFileSync(file, JSON.stringify({ pid, host: os.hostname(), startedAt: now }), { mode: 0o600 });
345
+ return { ok: true, holder: { pid, startedAt: now } };
346
+ }
347
+
348
+ /** Release the lock, but only if we still hold it (never free another's). */
349
+ function releaseLock(env = process.env, { pid = process.pid } = {}) {
350
+ const holder = lockHolder(env);
351
+ if (holder && holder.pid && holder.pid !== pid) return { ok: false, holder };
352
+ try {
353
+ fs.unlinkSync(lockPath(env));
354
+ return { ok: true };
355
+ } catch {
356
+ return { ok: true, already: true };
357
+ }
358
+ }
359
+
360
+ // ── run accounting ──────────────────────────────────────────────────────────
361
+
362
+ /**
363
+ * Append one finished run. Append-only and never rewritten: the queue is
364
+ * current state (and is deliberately small), the runs log is history, and
365
+ * history that can be truncated by a crash is not history.
366
+ */
367
+ function appendRun(env, record) {
368
+ const file = runsPath(env);
369
+ ensureDir(path.dirname(file));
370
+ fs.appendFileSync(file, JSON.stringify(record) + '\n', { mode: 0o600 });
371
+ return record;
372
+ }
373
+
374
+ function readRuns(env = process.env, { limit = 20 } = {}) {
375
+ let raw = '';
376
+ try {
377
+ raw = fs.readFileSync(runsPath(env), 'utf8');
378
+ } catch {
379
+ return [];
380
+ }
381
+ const lines = raw.split('\n').filter((l) => l.trim());
382
+ const slice = limit > 0 ? lines.slice(-limit) : lines;
383
+ const out = [];
384
+ for (const line of slice) {
385
+ try {
386
+ out.push(JSON.parse(line));
387
+ } catch {
388
+ /* same tolerance as readQueue */
389
+ }
390
+ }
391
+ return out;
392
+ }
393
+
394
+ // ── reconcile: pull the next PLAN.md phase into the queue ───────────────────
395
+ //
396
+ // PLAN.md carries a top `Status:` checklist (`- [x] Phase N — …`) plus one
397
+ // `## Phase N …` section per phase, marked done with a ✅ in the heading. The
398
+ // two have drifted here before (a phase shipped with a ✅ heading and no
399
+ // checklist line), so a phase counts as done if EITHER says so, and a missing
400
+ // checklist line under a ✅ heading is healed from the heading rather than
401
+ // silently re-queued as work.
402
+
403
+ function planPath(cwd) {
404
+ return path.join(cwd, 'PLAN.md');
405
+ }
406
+
407
+ function parsePlanStatus(text) {
408
+ const statusDone = new Map(); // phase number -> checked?
409
+ const headerDone = new Set(); // phase numbers whose heading carries ✅
410
+ const headerNums = new Set(); // every phase number with a heading
411
+ let inStatus = false;
412
+ for (const line of String(text || '').split('\n')) {
413
+ if (/^Status:/.test(line)) {
414
+ inStatus = true;
415
+ continue;
416
+ }
417
+ if (inStatus) {
418
+ const m = line.match(/^- \[([ x])\] Phase (\d+)/);
419
+ if (m) {
420
+ statusDone.set(Number(m[2]), m[1] === 'x');
421
+ continue;
422
+ }
423
+ // Blank lines and indented wraps belong to the same list item/block.
424
+ if (line.trim() === '' || /^\s+\S/.test(line)) continue;
425
+ inStatus = false; // anything else (e.g. '---') ends the block
426
+ }
427
+ // Every PLAN.md in these repos writes `## Phase 7 ✅ — title` (✅ right after
428
+ // the number). A trailing `## Phase 7 — title ✅` is accepted too, because
429
+ // reconcile reads plans other sessions and agents wrote, and a heading that
430
+ // says it shipped means it shipped wherever the ✅ sits.
431
+ const hm = line.match(/^##\s*Phase\s+(\d+)\b/);
432
+ if (hm) {
433
+ const num = Number(hm[1]);
434
+ headerNums.add(num);
435
+ if (/✅/.test(line.slice(hm[0].length))) headerDone.add(num);
436
+ }
437
+ }
438
+ return { statusDone, headerDone, headerNums };
439
+ }
440
+
441
+ function extractPhaseTitle(text, num) {
442
+ const m = String(text || '').match(new RegExp(`^## Phase ${num}\\b(.*)$`, 'm'));
443
+ if (!m) return `Phase ${num}`;
444
+ const rest = m[1]
445
+ .trim()
446
+ .replace(/^(✅|⚠️)\s*/, '')
447
+ .replace(/\s*(✅|⚠️)$/, '')
448
+ .replace(/^[—-]\s*/, '')
449
+ .trim();
450
+ return rest || `Phase ${num}`;
451
+ }
452
+
453
+ /** Append a checklist line for any ✅ heading the Status list never got. */
454
+ function healPlanStatus(text, parsed) {
455
+ const missing = [...parsed.headerDone].filter((n) => !parsed.statusDone.has(n)).sort((a, b) => a - b);
456
+ if (!missing.length) return { text, changed: false, added: [] };
457
+ const lines = String(text || '').split('\n');
458
+ const statusStart = lines.findIndex((l) => /^Status:/.test(l));
459
+ if (statusStart === -1) return { text, changed: false, added: [] };
460
+ let lastListIdx = -1;
461
+ for (let i = statusStart + 1; i < lines.length; i++) {
462
+ if (/^- \[[ x]\] Phase \d+/.test(lines[i])) {
463
+ lastListIdx = i;
464
+ continue;
465
+ }
466
+ if (lines[i].trim() === '' || /^\s+\S/.test(lines[i])) continue;
467
+ break;
468
+ }
469
+ if (lastListIdx === -1) return { text, changed: false, added: [] };
470
+ const newLines = missing.map((n) => `- [x] Phase ${n} — ${extractPhaseTitle(text, n)}`);
471
+ lines.splice(lastListIdx + 1, 0, ...newLines);
472
+ return { text: lines.join('\n'), changed: true, added: missing };
473
+ }
474
+
475
+ /**
476
+ * Read PLAN.md and say what the next uncompleted phase is, healing the Status
477
+ * checklist on the way (when `write` is true). Returns `{ ok, text, parsed,
478
+ * healed, next, title }` — the caller decides what to do with it, so the pure
479
+ * read is testable and nothing here queues on its own.
480
+ */
481
+ function reconcilePlan(cwd, { write = false } = {}) {
482
+ let text;
483
+ try {
484
+ text = fs.readFileSync(planPath(cwd), 'utf8');
485
+ } catch {
486
+ return { ok: false, reason: `no PLAN.md in ${cwd}`, next: null };
487
+ }
488
+ const parsed = parsePlanStatus(text);
489
+ const healed = healPlanStatus(text, parsed);
490
+ if (healed.changed && write) {
491
+ fs.writeFileSync(planPath(cwd), healed.text);
492
+ text = healed.text;
493
+ }
494
+ const done = new Set(parsed.headerDone);
495
+ for (const [num, checked] of parsed.statusDone) if (checked) done.add(num);
496
+ const next = [...parsed.headerNums].filter((n) => !done.has(n)).sort((a, b) => a - b)[0];
497
+ if (next == null) return { ok: true, text, parsed, healed, next: null, title: null };
498
+ return { ok: true, text, parsed, healed, next, title: extractPhaseTitle(text, next) };
499
+ }
500
+
501
+ module.exports = {
502
+ STATUSES,
503
+ dataDir,
504
+ queuePath,
505
+ runsPath,
506
+ lockPath,
507
+ ensureDir,
508
+ readQueue,
509
+ writeQueue,
510
+ loadQueue,
511
+ saveQueue,
512
+ nextId,
513
+ upsert,
514
+ addTask,
515
+ findTask,
516
+ markRunning,
517
+ settle,
518
+ retryTask,
519
+ clearQueue,
520
+ isAlive,
521
+ recoverStale,
522
+ pendingCount,
523
+ pending,
524
+ lockHolder,
525
+ acquireLock,
526
+ releaseLock,
527
+ appendRun,
528
+ readRuns,
529
+ planPath,
530
+ parsePlanStatus,
531
+ extractPhaseTitle,
532
+ healPlanStatus,
533
+ reconcilePlan,
534
+ };