@stevensuna/pi-interactive-agents

Product: Nexium Pi interactive worker runtime. npm scope is @stevensuna until the nexiumlab org exists on npm — see docs/NPM_SCOPE.md.

Interactive agent runtime for the Watcher control plane.

This package is a Pi extension that lets Watcher spawn and supervise fixed-role workers in cmux, tmux, zellij, or WezTerm panes. Watcher remains the sole control plane: lifecycle tools are registered only when WATCHER_PARENT=1.

Public Tools

Parent-only lifecycle tools:

| Tool | Purpose | | --- | --- | | watcher_worker_spawn | Spawn a fixed-role worker in a dedicated multiplexer pane | | watcher_worker_interrupt | Send Escape to a running Pi-backed worker turn | | watcher_workers_list | List running workers and available role definitions | | watcher_worker_resume | Resume a prior worker session in a new pane |

Child-only worker tools:

| Tool | Purpose | | --- | --- | | worker_ping | Ask Watcher for help and exit the worker session | | worker_done | Mark worker completion and exit the worker session |

No slash commands are registered. Watcher drives orchestration through tools.

Roles

Bundled roles live in workers/:

| Role | CLI | Model | Auto-exit | Interactive | | --- | --- | --- | --- | --- | | scanner | agy | agy/gemini-3.5-flash | yes | yes | | generator | codex | gpt-5.5 | yes | no | | generator-fallback | grok | grok-composer-2.5-fast | yes | no | | evaluator | claude | claude/opus | yes | no | | planner | claude | claude/opus | no | yes | | researcher | pi | grok-cli/grok-4.3 | yes | no | | browser | agy | agy/gemini-3.5-flash | yes | yes |

Role model mappings are enforced. Bundled roles default to their native CLI launchers; explicit Pi-backed overrides still fail fast unless the role/model pair is known launchable by this runtime. Set WATCHER_ALLOW_MODEL_OVERRIDE=1 only for development/testing overrides.

Launch UX

Watcher workers are intended to be spawned from an interactive Pi parent session. A non-interactive parent such as pi -p ... can still execute tools, but it may not keep the live Workers status renderer visible above the editor.

Native workers default to the trusted local launch form with the most reliable completion path for that CLI. Watcher writes the prompt to context/<worker>.md, prints a small human banner, then launches the native CLI in the worker pane with auto-approve permissions:

| Role | Expected command shape | | --- | --- | | scanner | printf 'Watcher worker: <name> | role=scanner cli=agy\n'; cd <cwd> && agy --dangerously-skip-permissions --model gemini-3.5-flash -i "$(cat <prompt-file>)" | | generator | printf 'Watcher worker: <name> | role=generator cli=codex\n'; codex --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust -c 'hooks.Stop=...' -m gpt-5.5 -C <cwd> "$(cat <prompt-file>)" | | generator-fallback | printf 'Watcher worker: <name> | role=generator-fallback cli=grok\n'; cd <cwd> && grok --always-approve --no-subagents -m grok-composer-2.5-fast --prompt-file <prompt-file> | | evaluator | printf 'Watcher worker: <name> | role=evaluator cli=claude\n'; cd <cwd> && claude --dangerously-skip-permissions --model opus --plugin-dir <plugin-dir> @<prompt-file> | | planner | printf 'Watcher worker: <name> | role=planner cli=claude\n'; cd <cwd> && claude --dangerously-skip-permissions --model opus --plugin-dir <plugin-dir> @<prompt-file> |

Native roles prefer interactive/TUI launches for pane-oriented work. Codex and Claude have lifecycle hooks that write ${WATCHER_WORKER_SESSION}.exit; bundled Agy scanner and browser roles run as interactive CLI panes and complete through the WATCHER_COMPLETE: OK token/screen fallback, or the stable terminal tail fallback, unless/until Agy exposes a deterministic per-invocation Stop hook. Grok generator-fallback stays on grok --prompt-file by default because process exit is the deterministic completion path for that fallback. worker_result is delivered when a deterministic sidecar appears, the CLI process exits, or an interactive fallback completes. Preferred (Layer 1): lifecycle hooks write ${WATCHER_WORKER_SESSION}.exit; Codex workers receive an ephemeral -c hooks.Stop=... override for the Watcher Stop hook, and Claude workers use the bundled Claude Stop hook. Fallback (Layer 2): wrapper process exits write the same .exit sidecar. Debug fallback (Layer 3): screen scraping recognizes completion tokens (WATCHER_COMPLETE: OK, BROWSER_PROBE_OK, HOOK_TEST_*, or WATCHER_COMPLETION_TOKEN regex) only after the terminal tail is stable for two polls with no busy markers. Legacy (off by default): per-CLI UI heuristics only when WATCHER_LEGACY_UI_DETECTORS=1. By default, worker panes close after worker_result is delivered.

Set WATCHER_WORKER_INTERACTIVE_CLI=0 to force native headless forms for all native CLIs where available. In that mode agy uses --print, claude uses -p @<prompt-file>, codex uses codex exec, and Grok uses --prompt-file. WATCHER_WORKER_STREAM=1 can wrap supported headless CLIs through stream-native-cli.sh; streaming is off by default.

Worker Pane UX

Worker panes close after completion by default. Set WATCHER_WORKER_CLOSE_PANE=0 to keep panes open for inspection while debugging.

cmux creates the first worker in a worker pane and then opens later workers as new surfaces in that pane. tmux and WezTerm split the first worker to the right of the parent and stack later workers downward from the previous worker surface. Zellij keeps its tab-aware placement logic.

When running in cmux, Watcher updates the workspace sidebar with cmux set-status watcher_worker '<role> · <cli> · <state>' and cmux set-progress ... --label '<role> · <cli> · <state>' as activity files change. These updates are cosmetic; worker completion still comes from the .exit sidecar. cmux settings such as autoResumeAgentSessions, agent hibernation, and native agent integrations can coexist with Watcher panes, but Watcher should not depend on those mechanisms for completion; the sidecar remains the contract.

Environment

Primary Watcher env vars:

| Variable | Purpose | | --- | --- | | WATCHER_PARENT=1 | Explicitly enable parent lifecycle tools | | (default) | Lifecycle tools on for non-worker Pi sessions; off when WATCHER_WORKER_ROLE / PI_SUBAGENT_AGENT is set | | WATCHER_PARENT=0 | Force-disable lifecycle tools on a parent session | | WATCHER_DENY_TOOLS | Comma-separated denied tool names | | WATCHER_MUX_BACKEND | Force cmux, tmux, zellij, or wezterm | | WATCHER_WORKER_DIR | Global worker config root | | WATCHER_WORKER_* | Worker identity/session/activity values passed to children | | WATCHER_WORKER_CLOSE_PANE | Close worker pane/surface on completion; default 1. Set 0 to keep panes open for inspection | | WATCHER_WORKER_INTERACTIVE_CLI | Use interactive native CLI mode where supported; default 1. Set 0 for retained headless native forms | | WATCHER_WORKER_SHELL_READY_DELAY_MS | Delay before sending launch command, default 500 | | WATCHER_WORKER_STREAM | Override native headless CLI stream wrapper use; default 0 | | WATCHER_WIDGET_TICK_MS | Above-editor Workers widget elapsed refresh, default 2000 | | WATCHER_ZELLIJ_MIN_COLUMNS | Minimum columns for Zellij worker panes, default 50 | | WATCHER_ZELLIJ_MIN_ROWS | Minimum rows for Zellij worker panes, default 10 |

Legacy PI_SUBAGENT_*, PI_DENY_TOOLS, PI_CODING_AGENT_DIR, and PI_SUBAGENT_ZELLIJ_MIN_COLUMNS/ROWS aliases are still read where needed for compatibility with existing Pi runtime paths.

Status delivery

Worker status is event-driven. On spawn/resume, Watcher creates and watches worker-activity/<worker-id>.json; Pi workers update it from extension hooks, and native CLI wrappers mark starting, active, and done phases through WATCHER_WORKER_ACTIVITY_FILE.

If a worker pane/tab is closed manually, supervision treats it as an error (Worker pane was closed before completion) and clears the Workers widget and cmux sidebar status when the last worker ends.

Completion is delivered by watching ${WATCHER_WORKER_SESSION}.exit, with Claude stop sentinels watched only for transcript-copy compatibility. A 5s terminal sentinel watchdog and completion-token screen contract remain fallbacks for missed filesystem events, explicitly interactive roles without lifecycle hooks, or abnormal process exits. Agy scanner/browser currently rely on the WATCHER_COMPLETE: OK token/screen fallback or stable terminal tail because Agy does not currently expose a deterministic per-invocation Stop hook equivalent to Codex -c hooks.Stop=.... Grok generator-fallback remains headless with --prompt-file so process exit stays deterministic for fallback generation. When a completion path fires, Watcher finalizes the activity file to phase: done before removing the worker from the running set.

Current limitation: if the parent Pi extension is reloaded or the parent session shuts down while a worker is mid-flight, the in-memory watcher is aborted and workers are not re-adopted automatically by scanning existing activity files. The worker pane may continue running, but automatic worker_result delivery requires the original supervising watcher to remain alive.

Session reuse rule of thumb: reuse watcher_worker_resume only when the prior session file still exists, the repo and task are still the same, and no reload or shutdown interrupted supervision. Spawn a new worker when the session file is gone, the task scope changed, or a reload interrupted the watcher. When reuse is not possible, prefer artifact handoff files over missing watcher session JSONL files.