@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/agent/observe.js

@@ -1,11 +1,16 @@
 import * as path from "node:path";
+import * as fs from "node:fs";
+import { SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { Container, TruncatedText } from "@earendil-works/pi-tui";
+import { actionText } from "../shared/tui-action.js";
 import { getPiAgentDir } from "../pi-intercom/agent-dir.js";
 import { isChild, errorText } from "./host.js";
 import { launchAt, list, ownerDirectory, runDirectory, read } from "./storage.js";
 import { successorSchema } from "./contracts.js";
 import { readCanonicalResult } from "./usage.js";
-import { actor, alive } from "./process.js";
-import { JournalTail, plainText } from "./journal-tail.js";
+import { actor, observeAlive } from "./process.js";
+import { plainText } from "./journal-tail.js";
+import { ObservationClient } from "./observe-client.js";
 import { adoptedJournal } from "./saved.js";
 const STATUS_KEY = "agent-observer";
 class Observer {
@@ -13,9 +18,16 @@ class Observer {
     owner = "";
     base = "";
     timer;
+    scanning;
+    rescan = false;
     close;
     refresh;
     rows = new Map();
+    peers = new Map();
+    watcher;
+    widgetVisible = false;
+    widgetSignature = "";
+    widgetRender;
     launches = new Map();
     finished = new Set();
     pending = [];
@@ -27,10 +39,22 @@ class Observer {
     }
     dispose() {
         clearInterval(this.timer);
+        this.timer = undefined;
+        this.scanning = undefined;
+        this.rescan = false;
+        this.watcher?.close();
+        this.watcher = undefined;
+        for (const peer of this.peers.values()) {
+            peer.client.close();
+        }
+        this.peers.clear();
+        this.widgetVisible = false;
+        this.widgetSignature = "";
+        this.widgetRender = undefined;
         this.close?.();
         this.close = undefined;
         this.refresh = undefined;
-        this.ctx?.ui.setStatus(STATUS_KEY, undefined);
+        this.ctx?.ui.setWidget(STATUS_KEY, undefined);
         this.ctx = undefined;
         this.rows.clear();
         this.launches.clear();
@@ -49,57 +73,75 @@ class Observer {
         this.ctx = ctx;
         this.owner = ctx.sessionManager.getSessionId();
         this.base = ownerDirectory(path.resolve(getPiAgentDir()), this.owner);
+        fs.mkdirSync(this.base, { recursive: true, mode: 0o700 });
+        try {
+            const watcher = fs.watch(this.base, { recursive: true }, (_event, file) => {
+                if (this.watcher === watcher &&
+                    this.timer === undefined &&
+                    (file === null || /(?:launch|result|successor|process)\.json$/.test(file))) {
+                    this.scan();
+                }
+            });
+            this.watcher = watcher;
+            watcher.on("error", () => {
+                if (this.watcher !== watcher) {
+                    return;
+                }
+                watcher.close();
+                this.watcher = undefined;
+                this.scan();
+            });
+        }
+        catch {
+            /* Sparse native execution events still wake inventory without an idle poll. */
+        }
         this.scan();
-        this.timer = setInterval(() => this.scan(), 1000);
-        this.timer.unref();
     }
     launch(id) {
         const launch = this.launches.get(id) ?? launchAt(this.base, id, this.owner);
         this.launches.set(id, launch);
         return launch;
     }
-    live(launch, roots) {
-        const cached = roots.get(launch.rootId);
-        if (cached !== undefined) {
-            return cached;
-        }
-        const identity = actor(this.base, launch);
-        const live = identity !== undefined && alive(identity);
-        roots.set(launch.rootId, live);
-        return live;
-    }
+    /** Reads durable metadata now; unfinished rows commit after their root's batched liveness. */
     load(id, roots) {
         if (this.finished.has(id)) {
-            return;
+            return undefined;
         }
         const launch = this.launch(id);
         const result = readCanonicalResult(this.base, launch);
         const finished = result !== undefined || this.hasSuccessor(id);
-        const live = !finished && this.live(launch, roots);
         if (finished) {
             this.finished.add(id);
         }
-        this.rows.set(id, {
-            id,
-            name: plainText(launch.name ?? id, 120),
-            status: result?.status ?? (live ? "running" : "interrupted"),
-            live,
-            createdAt: launch.createdAt,
-        });
+        else if (!roots.has(launch.rootId)) {
+            roots.set(launch.rootId, actor(this.base, launch));
+        }
+        return (live) => {
+            const running = !finished && live.get(launch.rootId) === true;
+            this.rows.set(id, {
+                id,
+                name: plainText(launch.name ?? id, 120),
+                status: result?.status ?? (running ? "running" : "interrupted"),
+                live: running,
+                createdAt: launch.createdAt,
+                activity: this.peers.get(id)?.client.activity,
+            });
+        };
     }
     hasSuccessor(id) {
         return (read(path.join(runDirectory(this.base, id), "successor.json"), successorSchema) !== undefined);
     }
     loadVisible(id, roots) {
         try {
-            this.load(id, roots);
+            return this.load(id, roots);
         }
         catch (error) {
             this.rows.set(id, { id, name: id, status: "unavailable", live: false, createdAt: 0 });
             this.error = plainText(errorText(error));
+            return undefined;
         }
     }
-    scan() {
+    loadBatch(roots) {
         try {
             const ids = list(this.base);
             const present = new Set(ids);
@@ -118,14 +160,161 @@ class Observer {
                 this.pending = ids.filter((id) => !this.finished.has(id));
             }
             this.error = "";
-            const roots = new Map();
-            this.pending.splice(0, 50).forEach((id) => this.loadVisible(id, roots));
+            return this.pending.splice(0, 50).flatMap((id) => this.loadVisible(id, roots) ?? []);
         }
         catch (error) {
             this.error = plainText(errorText(error));
+            return [];
+        }
+    }
+    /** One scan at a time; triggers during a scan coalesce into one follow-up. */
+    scan() {
+        if (this.scanning !== undefined) {
+            this.rescan = true;
+            return;
+        }
+        const scanning = this.update()
+            .catch((error) => {
+            this.error = plainText(errorText(error));
+        })
+            .finally(() => {
+            if (this.scanning !== scanning) {
+                return;
+            }
+            this.scanning = undefined;
+            if (this.rescan) {
+                this.rescan = false;
+                this.scan();
+            }
+        });
+        this.scanning = scanning;
+    }
+    async update() {
+        const ctx = this.ctx;
+        const roots = new Map();
+        const commits = this.loadBatch(roots);
+        const claims = [...roots].flatMap(([root, identity]) => (identity ? [{ root, identity }] : []));
+        const verdicts = await observeAlive(claims.map(({ identity }) => identity));
+        if (this.ctx !== ctx) {
+            return;
+        }
+        const live = new Map(claims.map(({ root }, index) => [root, verdicts[index]]));
+        for (const commit of commits) {
+            commit(live);
         }
-        this.ctx?.ui.setStatus(STATUS_KEY, this.status());
+        this.activity();
+        this.widget();
         this.refresh?.();
+        const periodic = this.pending.length > 0 || [...this.rows.values()].some((row) => row.live);
+        if (periodic && !this.timer) {
+            this.timer = setInterval(() => this.scan(), 1000);
+            this.timer.unref();
+        }
+        else if (!periodic) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    activity() {
+        const visible = this.strip()
+            .filter((entry) => entry.live)
+            .slice(0, 4);
+        const ids = new Set(visible.map((entry) => entry.id));
+        for (const [id, peer] of this.peers) {
+            if (!ids.has(id) || peer.client.closed) {
+                peer.client.close();
+                this.peers.delete(id);
+            }
+        }
+        for (const row of visible) {
+            if (this.peers.has(row.id)) {
+                continue;
+            }
+            try {
+                const launch = this.launch(row.id);
+                const identity = actor(this.base, launch);
+                if (!identity) {
+                    continue;
+                }
+                const client = new ObservationClient({ token: identity.token, rootId: launch.rootId, sessionId: launch.sessionId }, "activity", () => {
+                    if (this.peers.get(row.id)?.client !== client) {
+                        return;
+                    }
+                    const current = this.rows.get(row.id);
+                    if (current) {
+                        current.activity = client.connected ? client.activity : "Reconnecting";
+                    }
+                    this.widget();
+                });
+                this.peers.set(row.id, { token: identity.token, client });
+            }
+            catch {
+                // Older or not-yet-ready actors still have a known run status, but no live phase.
+            }
+        }
+    }
+    widget() {
+        const ctx = this.ctx;
+        if (!ctx) {
+            return;
+        }
+        const rows = this.strip();
+        if (rows.length === 0 && this.rows.size === this.total && this.error.length === 0) {
+            if (this.widgetVisible) {
+                ctx.ui.setWidget(STATUS_KEY, undefined);
+            }
+            this.widgetVisible = false;
+            this.widgetSignature = "";
+            return;
+        }
+        const signature = JSON.stringify([this.status(), rows.slice(0, 4), rows.length]);
+        if (signature === this.widgetSignature) {
+            return;
+        }
+        this.widgetSignature = signature;
+        if (this.widgetVisible) {
+            this.widgetRender?.();
+            return;
+        }
+        this.widgetVisible = true;
+        ctx.ui.setWidget(STATUS_KEY, (tui, theme) => {
+            this.widgetRender = () => {
+                tui.requestRender();
+            };
+            const content = new Container();
+            const open = (id) => {
+                if (ctx !== this.ctx) {
+                    return;
+                }
+                void this.show(id, ctx).catch((error) => {
+                    ctx.ui.notify(errorText(error), "error");
+                });
+            };
+            return {
+                render: (width) => {
+                    const strip = this.strip();
+                    const visible = strip.slice(0, 4);
+                    content.clear();
+                    content.addChild(actionText(theme.fg("accent", this.status()), () => open("")));
+                    for (const row of visible) {
+                        const glyph = row.live ? "●" : "○";
+                        const color = row.live ? "accent" : "warning";
+                        content.addChild(actionText(`${theme.fg(color, glyph)} ${theme.bold(row.name)} · ${row.activity ?? row.status}`, () => open(row.id)));
+                    }
+                    if (strip.length > visible.length) {
+                        content.addChild(actionText(theme.fg("dim", `+${strip.length - visible.length} more · /agents`), () => open("")));
+                    }
+                    if (this.error.length > 0) {
+                        content.addChild(new TruncatedText(theme.fg("warning", this.error), 0, 0));
+                    }
+                    return content.render(width);
+                },
+                handleMouse: (event) => content.handleMouse(event),
+                invalidate: () => {
+                    // Render reads current rows, expansion and theme on every frame.
+                },
+            };
+        }, { placement: "aboveEditor" });
     }
     status() {
         const active = [...this.rows.values()].filter((row) => row.live).length;
@@ -134,7 +323,9 @@ class Observer {
         return `Agents: ${active}${checking ? "+" : ""} active${checking ? " (checking…)" : ""} · ${this.total} runs${error} · /agents`;
     }
     inventory() {
-        return [...this.rows.values()].sort((a, b) => {
+        return [...this.rows.values()]
+            .filter((row) => row.status !== "completed")
+            .sort((a, b) => {
             const order = Number(b.live) - Number(a.live);
             if (order !== 0) {
                 return order;
@@ -143,6 +334,10 @@ class Observer {
             return created !== 0 ? created : a.id.localeCompare(b.id);
         });
     }
+    /** The always-visible strip shows active work and unreadable runs; /agents keeps history. */
+    strip() {
+        return this.inventory().filter((row) => row.live || row.status === "unavailable");
+    }
     watch(id) {
         const matches = list(this.base).filter((candidate) => candidate.startsWith(id));
         const exact = matches.includes(id);
@@ -171,11 +366,14 @@ class Observer {
             !adoptedJournal(this.base, launch)) {
             throw new Error("Child journal path is outside its saved conversation.");
         }
+        const identity = actor(this.base, launch);
         return {
-            tail: new JournalTail(launch.sessionFile, launch.sessionId),
-            file: launch.sessionFile,
-            id: launch.id,
-            inherited: launch.context === "fork",
+            launch,
+            identity: identity && {
+                token: identity.token,
+                rootId: launch.rootId,
+                sessionId: launch.sessionId,
+            },
         };
     }
     async show(args, ctx) {
@@ -193,6 +391,7 @@ class Observer {
             const screen = new ObserverScreen({
                 data: {
                     inventory: () => this.inventory(),
+                    checking: () => this.rows.size < this.total,
                     row: (id) => this.rows.get(id),
                     status: () => this.status(),
                     error: () => this.error,
@@ -203,24 +402,32 @@ class Observer {
                 keys,
                 done: () => done(true),
                 selected: args.trim(),
+                hideThinking: SettingsManager.create(ctx.cwd, getPiAgentDir()).getHideThinkingBlock(),
             });
             this.close = () => done(true);
             this.refresh = () => screen.update();
-            return {
-                render: (width) => screen.render(width),
-                handleInput: (data) => screen.handleInput(data),
-                invalidate: () => screen.invalidate(),
-                dispose: () => {
-                    screen.dispose();
-                    this.close = undefined;
-                    this.refresh = undefined;
-                },
+            const dispose = screen.dispose.bind(screen);
+            screen.dispose = () => {
+                dispose();
+                this.close = undefined;
+                this.refresh = undefined;
             };
+            return screen;
+        }, {
+            overlay: true,
+            overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 },
         });
     }
     register() {
         this.pi.on("session_start", (_event, ctx) => this.attach(ctx));
         this.pi.on("session_shutdown", () => this.dispose());
+        this.pi.on("tool_execution_end", (event) => {
+            if (this.ctx &&
+                this.watcher === undefined &&
+                (event.toolName === "delegate" || event.toolName === "agent_runs")) {
+                this.scan();
+            }
+        });
         this.pi.registerCommand("agents", {
             description: "List this parent's children; /agents <run-id or unique 8+ prefix> watches native activity read-only",
             handler: (args, ctx) => this.show(args, ctx),

package/dist/agent/parking.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parkedSchema } from "./contracts.js";
+import { errorText, loadSDK } from "./host.js";
+import { conversation, latest, launchAt, list, read, runDirectory, write } from "./storage.js";
+import { alive, shells, wakeActor } from "./process.js";
+import { isHistoryRequest, PARK, PARKED_HISTORY, WAKE, } from "../shared/parking.js";
+import { nativePeerId } from "../pi-intercom/session-targets.js";
+function parkable(session) {
+    return typeof Reflect.get(session, "acquireWorkingSession") === "function";
+}
+function finalizing(runtime) {
+    return typeof Reflect.get(runtime, "setFinalization") === "function";
+}
+function fence(pi, park) {
+    let fenced = Promise.resolve(false);
+    pi.events.emit(PARK, {
+        park,
+        reply: (parked) => {
+            fenced = parked;
+        },
+    });
+    return fenced;
+}
+async function cut(pi, session, { quiet, errors, signal }) {
+    try {
+        // Save handlers may legitimately append entries; only the pre-cut leaf proves idleness.
+        if ((await fence(pi, true)) && quiet() && session.isIdle) {
+            return await session.acquireWorkingSession({ boundary: "settled", signal });
+        }
+    }
+    catch (error) {
+        errors.push(errorText(error));
+    }
+    return undefined;
+}
+const PARK_AFTER_MS = 5 * 60_000;
+const digest = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+/** Parked authority names this session and exactly the saved generation's state bytes. */
+function exact(restore, parked, state, launch) {
+    if (parked.sessionId !== launch.sessionId ||
+        parked.state !== state ||
+        digest(state) !== parked.digest) {
+        return undefined;
+    }
+    const saved = restore(state);
+    return saved.sessionFile === launch.sessionFile &&
+        saved.header.id === launch.sessionId &&
+        saved.leafId === parked.leafId
+        ? saved
+        : undefined;
+}
+/** This child's exact parked generation, if any; mismatched authority restores nothing. */
+export function parkedState(dir, launch, restore) {
+    const parked = read(path.join(dir, "parked.json"), parkedSchema);
+    if (!parked) {
+        return undefined;
+    }
+    if (!restore) {
+        throw new Error("Parked working state needs the Pi fork that saved it; nothing was reopened.");
+    }
+    // Native working state requires a canonical parent, not a symlinked alias like macOS /var.
+    const state = path.join(fs.realpathSync(dir), `working-${parked.token}.json`);
+    const saved = exact(restore, parked, state, launch);
+    if (!saved) {
+        throw new Error("Parked working state is not this child's saved generation; nothing was reopened.");
+    }
+    return { state, saved };
+}
+/** One actor generation's idle parking and exact restore; commands stay with the runner. */
+export class Parking {
+    saved;
+    restored;
+    since = 0;
+    leaf;
+    base;
+    launch;
+    token;
+    sdk;
+    constructor(base, launch, token, sdk) {
+        this.base = base;
+        this.launch = launch;
+        this.token = token;
+        this.sdk = sdk;
+    }
+    get dir() {
+        return runDirectory(this.base, this.launch.rootId);
+    }
+    get file() {
+        return path.join(this.dir, "parked.json");
+    }
+    /** Parked authority is exact state or nothing; never a journal-only reopen. */
+    open() {
+        const { sdk, launch } = this;
+        const { openWorkingSession: restore } = sdk;
+        const parked = parkedState(this.dir, launch, restore && sdk.readWorkingSession);
+        if (!parked || !restore) {
+            return sdk.SessionManager.open(launch.sessionFile, undefined, launch.cwd);
+        }
+        this.saved = parked.saved;
+        this.restored = parked.state;
+        return restore(parked.saved);
+    }
+    /** The ready restored generation owns this state now; a later park writes a new cut. */
+    adopt() {
+        if (this.restored !== undefined) {
+            fs.rmSync(this.file);
+            fs.rmSync(this.restored, { force: true });
+        }
+    }
+    /** True once this generation has exited its runtime with or without parked authority. */
+    async park(runtime, actor) {
+        if (!actor.pi ||
+            !this.due(runtime.session, actor.busy) ||
+            shells(this.base, this.launch, this.token).some(alive)) {
+            return false;
+        }
+        const hold = await this.prepare(runtime, actor.pi, actor);
+        if (hold) {
+            await this.commit(runtime, hold, actor.errors);
+        }
+        return hold !== undefined;
+    }
+    /** Final idle: no run, turn, journal change or viewer since the period began. */
+    due(session, busy) {
+        const leaf = session.sessionManager.getLeafId();
+        if (busy || !session.isIdle || leaf !== this.leaf) {
+            this.leaf = leaf;
+            this.since = performance.now();
+            return false;
+        }
+        return performance.now() - this.since >= PARK_AFTER_MS;
+    }
+    /**
+     * Fence broker input, then hold a settled sleep-ready cut of the same quiet idle leaf. Any
+     * failure or raced command releases, unfences and keeps this actor resident.
+     */
+    async prepare(runtime, pi, { quiet, errors, signal }) {
+        const { session } = runtime;
+        this.since = performance.now();
+        if (!parkable(session) || !this.sdk.writeWorkingSession || !finalizing(runtime)) {
+            return undefined;
+        }
+        // A launcher that enqueues after this marker waits for exit, then wakes the saved state.
+        const marker = path.join(this.dir, "actor.lock", "parking.json");
+        write(marker, { at: Date.now() });
+        const hold = await cut(pi, session, {
+            quiet: () => quiet() && session.sessionManager.getLeafId() === this.leaf,
+            errors,
+            signal,
+        });
+        // Revalidate after the awaited fence and save, immediately before the irreversible commit.
+        if (hold?.sleepReady === true && quiet()) {
+            return hold;
+        }
+        await hold?.release();
+        await fence(pi, false);
+        fs.rmSync(marker, { force: true });
+        return undefined;
+    }
+    /** Commit: native strict exit, then capture; failure leaves no parked authority. */
+    async commit(runtime, hold, errors) {
+        const save = this.sdk.writeWorkingSession;
+        if (save && finalizing(runtime)) {
+            runtime.setFinalization((final) => this.capture(final, save), { strictShutdown: true });
+        }
+        // No await between release and dispose: native final exit fences new turns in this tick.
+        const released = hold.release();
+        const disposed = runtime.dispose();
+        try {
+            await Promise.all([released, disposed]);
+        }
+        catch (error) {
+            errors.push(errorText(error));
+        }
+        if (read(this.file, parkedSchema)?.token !== this.token) {
+            // Truthful boundary: retained input stays queued and nothing restarts implicitly.
+            write(path.join(this.dir, "park-failed.json"), { token: this.token, errors });
+        }
+    }
+    async capture(session, save) {
+        if (!parkable(session)) {
+            throw new Error("Native working state is unavailable.");
+        }
+        const hold = await session.acquireWorkingSession({ boundary: "settled" });
+        try {
+            if (!hold.sleepReady) {
+                throw new Error(`Final working state is not sleep-ready: ${hold.blockers.join("; ")}`);
+            }
+            const state = path.join(fs.realpathSync(this.dir), `working-${this.token}.json`);
+            save(state, hold.state);
+            hold.assertHeld();
+            write(this.file, {
+                token: this.token,
+                state,
+                digest: digest(state),
+                sessionId: this.launch.sessionId,
+                leafId: hold.state.leafId,
+            });
+        }
+        finally {
+            await hold.release();
+        }
+    }
+}
+/** The broker names a parked child by native peer ID; only this owner's conversations match. */
+function ownedRun(runs, peer) {
+    const launch = runs && typeof peer === "string"
+        ? list(runs.base)
+            .map((id) => launchAt(runs.base, id, runs.owner))
+            .find((candidate) => nativePeerId(candidate.sessionId) === peer)
+        : undefined;
+    return launch && runs && latest(runs.base, launch);
+}
+/** The captured leaf's root-to-leaf path, as a live session manager reports it. */
+function branchOf(state) {
+    const entries = new Map(state.entries.map((entry) => [entry.id, entry]));
+    const branch = [];
+    for (let entry = entries.get(state.leafId ?? ""); entry !== undefined; entry = entries.get(entry.parentId ?? "")) {
+        branch.unshift(entry);
+    }
+    return branch;
+}
+async function history(runs, peer) {
+    const launch = ownedRun(runs, peer);
+    const restore = launch && (await loadSDK(launch.sdk)).readWorkingSession;
+    const state = runs && launch && parkedState(conversation(runs.base, launch), launch, restore)?.saved;
+    return state && { getBranch: () => branchOf(state) };
+}
+/**
+ * Wakes this owner's parked children for broker input and reads their saved history.
+ * `runs` is undefined while this session owns no children.
+ */
+export function serveParked(pi, runs, signal) {
+    pi.events.on(WAKE, (peer) => {
+        // On failure, retained input stays queued at the broker until the next main registration.
+        (async () => {
+            const current = runs();
+            const launch = ownedRun(current, peer);
+            if (current && launch) {
+                await wakeActor(current.base, launch, signal);
+            }
+        })().catch((error) => {
+            console.error(`Agent wake: ${errorText(error)}`);
+        });
+    });
+    pi.events.on(PARKED_HISTORY, (request) => {
+        if (isHistoryRequest(request)) {
+            request.reply(history(runs(), request.peer));
+        }
+    });
+}