wake-agent: event-triggered headless agent continuations, plus a session-footer indicator #281

New issue

Open

opened 2026-10-20 05:19:28 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-10-20 05:19:28 +01:00

Contributor

Primary goals:

One command, one contract — wake-agent <probe-cmd> <brief-file> runs as a detached user process; when <probe-cmd> succeeds it invokes pi --no-session -p "$(cat brief)" with a timeout, logging to a known file.
Failure is a written branch, not silence — a cap, a dead-target branch and a single-retry knob; every exit writes a status file naming the stage, so a cold reader knows what happened without the transcript.
The brief is the interface — the spawned agent is a fresh session with no memory; the brief file carries context pointers, the task, the stops, and the report path. The tool enforces nothing else.
Visible when running — a small TUI extension renders a footer badge (extension status / setFooter, docs/tui.md) driven by the same sentinel file the watcher touches, so any session on the machine shows wake-agent: running at a glance.
Proven before promoted — one clean end-to-end pilot (event fires, agent resumes, artifact lands, report written) gates the durable form; until then this stays userspace glue, not a NixOS module.

Current state and specifics

The pieces all exist separately; only the convention is missing. Headless runs are pi --no-session -p (docs/../usage); the deployment already fires agent flows from systemd timers (the memory-trace timer in allod/archetypes modules/memory-tracks.nix, OnCalendar=hourly), and extension footer hooks are documented in docs/tui.md (setFooter, persistent status entries). A pilot has run the pattern by hand: a shell watcher polled a log marker on a remote host every 5 minutes with a cap and a single bounded retry, then spawned a headless agent with a written work order (verify, implement against a live system, cold-review, PR, and stop at named human gates with a report). It worked; it is also one-off, undistributed, unpolished, and invisible in any session UI — exactly the gap.

Design notes from the pilot: the watcher must never trust a single liveness probe (a dying process and a working one look alike; re-check after a grace sleep); failure branches must write artifacts, not just exit codes; the spawned agent's brief must be self-contained because it inherits nothing; and a 90-minute timeout is enough for a focused single-PR turn but should be a parameter. The sentinel file (touched on start, on spawn, on exit, with the log path inside) is what makes the footer indicator trivial and the state inspectable by anything, not just the TUI.

Scope

In: the wake-agent CLI (wait/retry/timeout/status-file contract), the sentinel-file convention, the footer-badge extension reading it, and the pilot gate. Out: in-harness subagent spawning (pi intentionally runs continuations as separate sessions); general workflow orchestration — this is one event, one agent, one brief; and any deployment-specific wiring, which stays in the deployment's own repos. A clickable pop-open trace view is a possible later slice; the badge plus tail -f on the log is the v1.

Give long-running agent work a way to resume itself: a small tool that waits on an external event, then spawns a fresh headless agent with a written brief, plus a session-footer indicator that shows when such a continuation is live. Primary goals: - **One command, one contract** — `wake-agent <probe-cmd> <brief-file>` runs as a detached user process; when `<probe-cmd>` succeeds it invokes `pi --no-session -p "$(cat brief)"` with a timeout, logging to a known file. - **Failure is a written branch, not silence** — a cap, a dead-target branch and a single-retry knob; every exit writes a status file naming the stage, so a cold reader knows what happened without the transcript. - **The brief is the interface** — the spawned agent is a fresh session with no memory; the brief file carries context pointers, the task, the stops, and the report path. The tool enforces nothing else. - **Visible when running** — a small TUI extension renders a footer badge (extension status / `setFooter`, `docs/tui.md`) driven by the same sentinel file the watcher touches, so any session on the machine shows `wake-agent: running` at a glance. - **Proven before promoted** — one clean end-to-end pilot (event fires, agent resumes, artifact lands, report written) gates the durable form; until then this stays userspace glue, not a NixOS module. ### Current state and specifics The pieces all exist separately; only the convention is missing. Headless runs are `pi --no-session -p` (`docs/../usage`); the deployment already fires agent flows from systemd timers (the memory-trace timer in `allod/archetypes` `modules/memory-tracks.nix`, `OnCalendar=hourly`), and extension footer hooks are documented in `docs/tui.md` (`setFooter`, persistent status entries). A pilot has run the pattern by hand: a shell watcher polled a log marker on a remote host every 5 minutes with a cap and a single bounded retry, then spawned a headless agent with a written work order (verify, implement against a live system, cold-review, PR, and stop at named human gates with a report). It worked; it is also one-off, undistributed, unpolished, and invisible in any session UI — exactly the gap. Design notes from the pilot: the watcher must never trust a single liveness probe (a dying process and a working one look alike; re-check after a grace sleep); failure branches must write artifacts, not just exit codes; the spawned agent's brief must be self-contained because it inherits nothing; and a 90-minute timeout is enough for a focused single-PR turn but should be a parameter. The sentinel file (touched on start, on spawn, on exit, with the log path inside) is what makes the footer indicator trivial and the state inspectable by anything, not just the TUI. ### Scope In: the `wake-agent` CLI (wait/retry/timeout/status-file contract), the sentinel-file convention, the footer-badge extension reading it, and the pilot gate. Out: in-harness subagent spawning (pi intentionally runs continuations as separate sessions); general workflow orchestration — this is one event, one agent, one brief; and any deployment-specific wiring, which stays in the deployment's own repos. A clickable pop-open trace view is a possible later slice; the badge plus `tail -f` on the log is the v1.