agent-lyceum 0.21.1 → 0.21.2

package/dist/cli.js

@@ -23,6 +23,7 @@ import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
 import { runMonitor } from "./monitor-lifecycle.js";
+import { createStatusWatcher } from "./status-watch.js";
 import { LAUNCH_PPID, startedByWrapper, watchParent } from "./parent-watch.js";
 import { onlyAgent, soloProject } from "./solo.js";
 import { DEMO_PROJECT, DEMO_TASK, defaultDemoDir, detectRuntime, prepareDemo } from "./demo.js";
@@ -758,8 +759,40 @@ program
     .option("--monitor", "keep the page open and refresh it (Ctrl-C to quit)")
     .option("--interval <sec>", "refresh interval for --monitor", "2")
     .option("--json", "print the report as JSON (no colour); works with --task-list and --task-id")
+    .option("--watch", "with --json: keep running and print one JSON line (the project report plus one per running task) whenever it changes (Ctrl-C to quit)")
+    .option("--heartbeat <sec>", "with --watch: how often to re-check when no file event came", "5")
     .action(async (opts) => {
     try {
+        if (opts.watch) {
+            if (!opts.json)
+                fail("--watch needs --json.");
+            if (opts.monitor || opts.taskList || opts.taskId !== undefined)
+                fail("--watch cannot be combined with --monitor, --task-list or --task-id.");
+            const beat = Number(opts.heartbeat);
+            if (!(beat > 0))
+                fail("--heartbeat must be a positive number of seconds.");
+            loadProject(opts.project); // fail now on an unknown project, not as a frame
+            const watcher = createStatusWatcher({
+                load: () => loadProject(opts.project),
+                dir: (p) => p.paths.runs,
+                write: (line) => process.stdout.write(`${line}\n`),
+                debounceMs: 100,
+            });
+            runMonitor({
+                draw: watcher.beat,
+                intervalMs: beat * 1000,
+                stdout: process.stdout,
+                stdin: process.stdin,
+                ppid: () => process.ppid,
+                exit: (code) => {
+                    watcher.close();
+                    process.exit(code);
+                },
+                onSignal: (sig, handler) => process.on(sig, handler),
+                fail: (message) => fail(message),
+            });
+            await new Promise(() => { });
+        }
         const pr = loadProject(typeof opts.taskList === "string" ? opts.taskList : opts.project);
         if (opts.json) {
             if (opts.monitor)

package/dist/status-watch.d.ts

@@ -0,0 +1,35 @@
+import type { ResolvedProject } from "./config.js";
+import { type StatusReport } from "./status.js";
+/** What `status --json --watch` prints, one JSON object per line: the project's report plus one per running task. */
+export type WatchFrame = {
+    schema_version: 1;
+    report?: StatusReport;
+    runs?: Record<string, StatusReport>;
+    error?: string;
+};
+/**
+ * The frame for now. Every running task gets its own report; a task that was running in the previous frame
+ * and has ended since is included once more, so the reader sees it finish (and can toast) before it is dropped.
+ * `tracked` is that previous set; it is replaced by the ids running now.
+ */
+export declare function buildWatchFrame(project: ResolvedProject, tracked: Set<string>): WatchFrame;
+export interface WatchDeps {
+    /** The project, loaded again each time so config edits and new runs show up. */
+    load: () => ResolvedProject;
+    /** The directory whose changes mean the status may have changed (the project's runs directory). */
+    dir: (project: ResolvedProject) => string;
+    write: (line: string) => void;
+    debounceMs: number;
+    watch?: (dir: string, onChange: () => void) => {
+        close: () => void;
+    };
+}
+/**
+ * Print a frame now and again whenever something under the runs directory changes (debounced; a round writes several files).
+ * A frame equal to the last one is not printed. `beat()` is the slow fallback: it re-arms a watcher that could not start
+ * (the directory did not exist yet), and picks up what a missed file event or a dead lock holder left unnoticed.
+ */
+export declare function createStatusWatcher(d: WatchDeps): {
+    beat: () => void;
+    close: () => void;
+};

package/dist/status-watch.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import { buildStatusReport, buildTaskListReport } from "./status.js";
+/**
+ * The frame for now. Every running task gets its own report; a task that was running in the previous frame
+ * and has ended since is included once more, so the reader sees it finish (and can toast) before it is dropped.
+ * `tracked` is that previous set; it is replaced by the ids running now.
+ */
+export function buildWatchFrame(project, tracked) {
+    const running = buildTaskListReport(project)
+        .runs.filter((r) => r.state === "running")
+        .map((r) => r.run_id);
+    const runs = {};
+    for (const id of new Set([...running, ...tracked]))
+        runs[id] = buildStatusReport(project, id);
+    const report = buildStatusReport(project);
+    tracked.clear();
+    for (const id of running)
+        tracked.add(id);
+    return { schema_version: 1, report, runs };
+}
+function fsWatch(dir, onChange) {
+    return fs.watch(dir, { recursive: true }, onChange);
+}
+/**
+ * Print a frame now and again whenever something under the runs directory changes (debounced; a round writes several files).
+ * A frame equal to the last one is not printed. `beat()` is the slow fallback: it re-arms a watcher that could not start
+ * (the directory did not exist yet), and picks up what a missed file event or a dead lock holder left unnoticed.
+ */
+export function createStatusWatcher(d) {
+    const tracked = new Set();
+    const watch = d.watch ?? fsWatch;
+    let lastLine = "";
+    let watching = "";
+    let watcher;
+    let timer;
+    const emit = () => {
+        let frame;
+        let project;
+        try {
+            project = d.load();
+            frame = buildWatchFrame(project, tracked);
+        }
+        catch (e) {
+            frame = { schema_version: 1, error: e.message };
+        }
+        const line = JSON.stringify(frame);
+        if (line !== lastLine) {
+            lastLine = line;
+            d.write(line);
+        }
+        if (project)
+            arm(d.dir(project));
+    };
+    const arm = (dir) => {
+        if (watcher && watching === dir)
+            return;
+        watcher?.close();
+        watcher = undefined;
+        if (!fs.existsSync(dir))
+            return;
+        try {
+            watcher = watch(dir, schedule);
+            watching = dir;
+        }
+        catch {
+            /* recursive watch unsupported or the directory vanished: the beat covers it */
+        }
+    };
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(emit, d.debounceMs);
+    };
+    return {
+        beat: emit,
+        close: () => {
+            if (timer)
+                clearTimeout(timer);
+            watcher?.close();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",