feat(agent-queue): macOS LaunchAgent boot-persistence (auto-start + KeepAlive)
Adds agent-queue-boot.sh (PATH repair + ~/.agent-queue.env overrides + caffeinate wrap) and launchd/ (install.sh + README) so the run loop auto-starts on login and survives reboot/crash — the persistence layer tmux+caffeinate alone cannot give. No secrets tracked (host config lives in untracked ~/.agent-queue.env). Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
saravanakumardb1
parent
f7999fb11b
commit
d574f5dda3
48
agent-queue/agent-queue-boot.sh
Executable file
48
agent-queue/agent-queue-boot.sh
Executable file
@ -0,0 +1,48 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
#
|
||||||
|
# agent-queue-boot.sh — boot/login entrypoint for the agent-queue run loop.
|
||||||
|
#
|
||||||
|
# Launched by the macOS LaunchAgent (see launchd/) so the folder-kanban worker
|
||||||
|
# auto-starts on login AND survives reboot/crash (LaunchAgent KeepAlive). This is
|
||||||
|
# the reboot-persistence layer that tmux + caffeinate alone cannot provide.
|
||||||
|
#
|
||||||
|
# It does three things launchd's minimal environment needs:
|
||||||
|
# 1. Repairs PATH so the agent CLIs (codex/devin/claude) + caffeinate are found.
|
||||||
|
# 2. Loads optional overrides from ~/.agent-queue.env.
|
||||||
|
# 3. Wraps `agent-queue run` in caffeinate (macOS) so the Mac won't sleep while
|
||||||
|
# a job is running. NOTE: because the run loop is long-lived, this keeps the
|
||||||
|
# machine awake for as long as the LaunchAgent runs — intended for a dedicated
|
||||||
|
# overnight runner. Set AGENT_QUEUE_NO_CAFFEINATE=1 to allow idle sleep.
|
||||||
|
#
|
||||||
|
set -uo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
|
||||||
|
|
||||||
|
# launchd hands processes a bare PATH — prepend the usual CLI install locations
|
||||||
|
# (Homebrew arm64/intel, ~/.local/bin for devin, system dirs) ahead of it.
|
||||||
|
export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH:-}"
|
||||||
|
|
||||||
|
# Optional per-machine overrides (engine, concurrency, tokens, NETWORK, etc.).
|
||||||
|
# This file is NOT tracked — keep secrets/host-specific config here.
|
||||||
|
if [ -f "$HOME/.agent-queue.env" ]; then
|
||||||
|
# shellcheck disable=SC1091
|
||||||
|
. "$HOME/.agent-queue.env"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Recommended default for a local monorepo overnight runner (see long-running-jobs
|
||||||
|
# cheat sheet): codex runs in-repo so @bytelyst/* workspace links resolve locally.
|
||||||
|
: "${AGENT_QUEUE_ENGINE:=codex}"
|
||||||
|
export AGENT_QUEUE_ENGINE
|
||||||
|
|
||||||
|
echo "[agent-queue-boot] $(date '+%Y-%m-%d %H:%M:%S') starting run loop" \
|
||||||
|
"(engine=$AGENT_QUEUE_ENGINE, max=${AGENT_QUEUE_MAX:-3})"
|
||||||
|
|
||||||
|
# Keep the Mac awake for the lifetime of the loop unless explicitly opted out.
|
||||||
|
keep=""
|
||||||
|
if [ "${AGENT_QUEUE_NO_CAFFEINATE:-0}" != "1" ] && command -v caffeinate >/dev/null 2>&1; then
|
||||||
|
keep="caffeinate -dimsu"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# exec so the LaunchAgent tracks the real worker PID (clean KeepAlive restarts).
|
||||||
|
# shellcheck disable=SC2086
|
||||||
|
exec $keep "$SCRIPT_DIR/agent-queue.sh" run
|
||||||
70
agent-queue/launchd/README.md
Normal file
70
agent-queue/launchd/README.md
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
# Boot-persistence: agent-queue as a macOS LaunchAgent
|
||||||
|
|
||||||
|
Auto-start the `agent-queue` run loop on login and keep it alive across
|
||||||
|
**reboot / crash / logout** — the one failure mode that `tmux` + `caffeinate`
|
||||||
|
alone can't cover.
|
||||||
|
|
||||||
|
| Layer | Survives terminal close | Survives sleep | Survives reboot |
|
||||||
|
| ----- | :---------------------: | :------------: | :-------------: |
|
||||||
|
| plain shell | no | no | no |
|
||||||
|
| `tmux` | yes | no | no |
|
||||||
|
| `caffeinate` | n/a | yes | no |
|
||||||
|
| **LaunchAgent (this)** | yes | yes (via caffeinate) | **yes** |
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash launchd/install.sh # render plist, load, start now (RunAtLoad + KeepAlive)
|
||||||
|
tail -f ~/Library/Logs/agent-queue/agent-queue.out.log
|
||||||
|
```
|
||||||
|
|
||||||
|
It renders `~/Library/LaunchAgents/com.bytelyst.agent-queue.plist` from the
|
||||||
|
resolved repo path (works on any clone) and bootstraps it into your GUI session.
|
||||||
|
|
||||||
|
## Use
|
||||||
|
|
||||||
|
The LaunchAgent runs `agent-queue-boot.sh`, which wraps `agent-queue run` in
|
||||||
|
`caffeinate`. Just drop prompt `.md` files into `queue/inbox/` — they get picked
|
||||||
|
up automatically, now or after the next reboot.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aq add ~/jobs/phase3-overnight.md --engine codex # or drop the file in queue/inbox/
|
||||||
|
aqs # status
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configure (no need to edit the plist)
|
||||||
|
|
||||||
|
Put overrides in `~/.agent-queue.env` (untracked — also the place for tokens):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
AGENT_QUEUE_ENGINE=codex # codex (recommended: local repo) | devin | claude
|
||||||
|
AGENT_QUEUE_MAX=1 # concurrent jobs on this host (default 3)
|
||||||
|
# AGENT_QUEUE_NO_CAFFEINATE=1 # allow the Mac to idle-sleep (NOT for overnight runs)
|
||||||
|
# DEVIN_BIN=/custom/path/devin # if a CLI isn't on the default PATH
|
||||||
|
```
|
||||||
|
|
||||||
|
## Stop / uninstall
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash launchd/install.sh --uninstall # bootout + remove plist (queued jobs stay put)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notes & gotchas
|
||||||
|
|
||||||
|
- **codex vs devin:** for a local monorepo overnight runner, **codex** is the
|
||||||
|
default — it runs in-repo so `@bytelyst/*` workspace links resolve locally and
|
||||||
|
logs/token-usage parsing already work. Use **devin** when you want a cloud
|
||||||
|
sandbox doing the heavy lifting (and ACUs/network aren't a concern).
|
||||||
|
- **Power:** caffeinate wraps the long-lived loop, so the Mac stays awake the
|
||||||
|
whole time the LaunchAgent runs. That's intended for a dedicated runner. Set
|
||||||
|
`AGENT_QUEUE_NO_CAFFEINATE=1` if you'd rather let it idle-sleep when no job is
|
||||||
|
active. Keep it plugged in with the lid open for true overnight runs.
|
||||||
|
- **PATH:** launchd starts processes with a minimal `PATH`. Both the plist
|
||||||
|
(`EnvironmentVariables`) and the wrapper repair it, but if a CLI lives
|
||||||
|
somewhere unusual, point at it explicitly via `~/.agent-queue.env`.
|
||||||
|
- **Dangerous mode:** jobs run `--yolo` (auto-approve) by default. The safety net
|
||||||
|
is the agent-queue lifecycle itself — jobs land in `review/` → `testing/` and
|
||||||
|
**shipping is always a manual human gate**. Never let an unattended run touch
|
||||||
|
`main`; push to a branch and open one PR.
|
||||||
|
- **Auth:** cache `gh auth login` / git credentials and the agent CLI's auth
|
||||||
|
before relying on it overnight, or the first `push` will block forever.
|
||||||
105
agent-queue/launchd/install.sh
Executable file
105
agent-queue/launchd/install.sh
Executable file
@ -0,0 +1,105 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
#
|
||||||
|
# install.sh — install (or remove) the macOS LaunchAgent that auto-starts the
|
||||||
|
# agent-queue run loop on login and keeps it alive across reboot/crash.
|
||||||
|
#
|
||||||
|
# bash launchd/install.sh # render plist, load, and start now
|
||||||
|
# bash launchd/install.sh --uninstall # stop, unload, and remove the plist
|
||||||
|
#
|
||||||
|
# The plist is generated from the resolved repo path so it works on any clone.
|
||||||
|
# Logs land in ~/Library/Logs/agent-queue/.
|
||||||
|
#
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
|
||||||
|
AQ_DIR="$(cd -- "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd -P)"
|
||||||
|
WRAPPER="$AQ_DIR/agent-queue-boot.sh"
|
||||||
|
|
||||||
|
LABEL="com.bytelyst.agent-queue"
|
||||||
|
PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
|
||||||
|
LOG_DIR="$HOME/Library/Logs/agent-queue"
|
||||||
|
UID_NUM="$(id -u)"
|
||||||
|
DOMAIN="gui/$UID_NUM"
|
||||||
|
|
||||||
|
if [ "$(uname -s)" != "Darwin" ]; then
|
||||||
|
echo "install.sh: macOS only (LaunchAgents). On Linux use a systemd --user unit." >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
uninstall() {
|
||||||
|
echo "[launchd] booting out $LABEL ..."
|
||||||
|
launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
|
||||||
|
rm -f "$PLIST"
|
||||||
|
echo "[launchd] removed $PLIST"
|
||||||
|
echo "[launchd] (the run loop is stopped; queued jobs stay in queue/inbox/)"
|
||||||
|
}
|
||||||
|
|
||||||
|
if [ "${1:-}" = "--uninstall" ] || [ "${1:-}" = "-u" ]; then
|
||||||
|
uninstall
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
[ -f "$WRAPPER" ] || { echo "install.sh: missing $WRAPPER" >&2; exit 1; }
|
||||||
|
chmod +x "$WRAPPER" "$AQ_DIR/agent-queue.sh" 2>/dev/null || true
|
||||||
|
mkdir -p "$HOME/Library/LaunchAgents" "$LOG_DIR"
|
||||||
|
|
||||||
|
echo "[launchd] writing $PLIST"
|
||||||
|
cat > "$PLIST" <<EOF
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>$LABEL</string>
|
||||||
|
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>/bin/bash</string>
|
||||||
|
<string>$WRAPPER</string>
|
||||||
|
</array>
|
||||||
|
|
||||||
|
<!-- Start on login and restart if it ever exits non-zero (crash/reboot). -->
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<dict>
|
||||||
|
<key>SuccessfulExit</key>
|
||||||
|
<false/>
|
||||||
|
</dict>
|
||||||
|
<!-- Guard against tight crash loops. -->
|
||||||
|
<key>ThrottleInterval</key>
|
||||||
|
<integer>30</integer>
|
||||||
|
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>$AQ_DIR</string>
|
||||||
|
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>$LOG_DIR/agent-queue.out.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>$LOG_DIR/agent-queue.err.log</string>
|
||||||
|
|
||||||
|
<!-- launchd's PATH is minimal; the wrapper also repairs PATH defensively. -->
|
||||||
|
<key>EnvironmentVariables</key>
|
||||||
|
<dict>
|
||||||
|
<key>PATH</key>
|
||||||
|
<string>$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||||
|
<key>AGENT_QUEUE_ENGINE</key>
|
||||||
|
<string>codex</string>
|
||||||
|
</dict>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Reload cleanly (bootout first so a re-run picks up plist changes).
|
||||||
|
launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
|
||||||
|
launchctl bootstrap "$DOMAIN" "$PLIST"
|
||||||
|
launchctl enable "$DOMAIN/$LABEL"
|
||||||
|
launchctl kickstart -k "$DOMAIN/$LABEL"
|
||||||
|
|
||||||
|
echo "[launchd] installed + started: $LABEL"
|
||||||
|
echo "[launchd] status : launchctl print $DOMAIN/$LABEL | sed -n '1,20p'"
|
||||||
|
echo "[launchd] logs : tail -f $LOG_DIR/agent-queue.out.log"
|
||||||
|
echo "[launchd] stop : bash $SCRIPT_DIR/install.sh --uninstall"
|
||||||
|
echo
|
||||||
|
echo "Drop prompt .md files into: $AQ_DIR/queue/inbox/"
|
||||||
|
echo "Override engine/concurrency/secrets in ~/.agent-queue.env (e.g. AGENT_QUEUE_MAX=1)."
|
||||||
Loading…
Reference in New Issue
Block a user