Run a companion plugin under the same host
A jp invocation runs a single command plugin. When one plugin needs a companion plugin running alongside it (for example, jp vite serve running jp review serve to serve review endpoints on the docs site), the outer plugin currently has to spawn a second jp child process.
Cost of a nested host process
- The outer plugin must translate its own
shutdownmessage into an OS signal for the childjpprocess and wait for it to exit, pushing process and signal management into the plugin. - Shutdown timeouts stack: the outer plugin's
shutdown_timeout_secsmust exceed the inner plugin's timeout, or the outer host will kill the process group while the inner host is still stopping an in-flight turn. - Pressing Ctrl-C reaches only the outer host, where the topmost interrupt handler belongs to the outer plugin rather than the inner host's running turn. As a result, Ctrl-C cannot stop just the active turn the way it does under a single host.
- Both hosts load the workspace and resolve configuration independently.
Current host architecture
All references below are in crates/jp_cli/src/cmd/plugin/dispatch.rs unless noted otherwise:
run_externalresolves and admits a single plugin, then callsrun_plugin(name, binary, args, &mut Ctx), which holds&mut Ctxuntil the plugin exits.- Per-plugin runtime state is already local to
run_plugin: the child process tree, stdin writer, stdout reader channel,JoinSetof delegated turns,RunningTurns,LateWrites, interrupt handler registration, and shutdown budget claim. - The process-wide services already support multiple registrants:
ShutdownBudgets(shutdown.rs) waits for the maximum claimed timeout, andSignalRouter(signals.rs) maintains a stack of interrupt handlers. - The plugin message loop is sequential. It requires
&mut Ctxforhandle_request(&mut ctx.workspace) and forprepare_turn, which callsctx.mcp_client.set_servers,configure_active_mcp_servers, andswap_config. Delegated turns then execute on background tasks. edit_filesruns synchronously inside the message loop and blocks it while the user's editor is open.- RFD 113 Phase 1 (Accepted, tracked by T-0syqmp1) refactors
run_plugin,message_loop, and the request handlers to takeCliCtxandWorkspaceCtxand removesswap_config.
Candidate designs
- Single event loop multiplexing both plugins. The host selects across both plugins' reader channels and dispatches requests sequentially, keeping per-plugin state in a struct per plugin instance.
Ctxownership remains unchanged, though a synchronous request likeedit_filesblocks both plugins while the editor is open. - Concurrent
run_plugintasks. Each plugin runs its own message loop, which requires sharing workspace and MCP state without an exclusive&mut Ctxborrow across the entire run. RFD 113 Phase 1 performs most of that context decomposition.
Open questions for the RFD
- Discovery and startup: whether a companion plugin is started via a protocol request from the primary plugin (
start_pluginwith command and args), declared in the plugin manifest, or configured in.jp/config.toml. A protocol request lets the primary plugin pass runtime arguments such as a dynamically bound port. - Admission policy: the companion plugin must pass
admitand its ownrunpolicy, and an interactive approval prompt requires a terminal that the primary plugin may already be using. - Lifecycle notifications: how the primary plugin learns that the companion is ready, which address or port it bound, and when it exits.
- Failure coupling: whether the companion exiting terminates the primary plugin, and vice versa.
- Shutdown ordering: in what order the two plugins receive
shutdown, and how theirshutdown_timeout_secsbudgets combine. - Idle Ctrl-C routing: when no turn is running, Ctrl-C reaches only the top plugin handler on the signal stack; stopping one plugin should cleanly shut down both.
- Turn isolation: an
interruptrequest from one plugin must not stop a turn started by the other plugin (RunningTurnsis currently keyed only byConversationId). - Terminal output: both plugins share a single
Printer.
Filed while designing RFD D72 (jp-review), which initially spawns a nested jp host process.