Module install_handlers 

install.start / install.cancel RPC handlers.

Phase α of SPEC_AGENT_INSTALL_STAGE_2026_05_17.md. Spawns npm install <package> for the requested provider, streams every line of stdout+stderr to install_chunk WPS events scoped to install:<sessionId>, and emits a terminal { op: "done", ok, error? } event when the child exits (or the user cancels).

Phase α scope:

• npm-only install (existing per-version layout at ~/.agentmux/<version>/cli/<provider>/).
• Plain piped stdio (no PTY) — npm doesn’t isatty-gate its output line-by-line, so pipes are fine here. PTY would be required for interactive post-install steps (Phase δ).
• Single in-flight install per session id. The frontend modal owns the session id and prevents parallel installs at the UI layer.
• Cancel kills the child via kill_on_drop when the abort handle fires. The partial node_modules dir is rm-rf’d best-effort.
• No verify / doctor / post-install steps yet — those land in Phase β.

Structs

InstallCancelReq 🔒

InstallCheckReq 🔒

InstallSessionRegistry

Per-session abort handle so install.cancel can kill an in-flight install. Also tracks active_providers so concurrent sessions for the same provider directory are rejected — without that, cancel of one would rm_rf the shared dir mid-install for the other. parking_lot::Mutex since the engine is sync at the handler boundary.

InstallStartReq 🔒

Constants

COMMAND_INSTALL_CANCEL

COMMAND_INSTALL_CHECK

COMMAND_INSTALL_START

COMMAND_RESOLVE_PREREQS

Functions

is_safe_cli_command 🔒

CLI command names are joined into the bin-resolution path; same allowlist as provider ids, plus . (some real CLIs include dots, e.g. eslint.cmd).

is_safe_provider_id 🔒

Provider ids feed into the install dir path; reject anything that could escape ~/.agentmux/<version>/cli/<provider>/.

provider_install_dir 🔒

Canonical install directory for a provider — <agentmux_home>/instances/v<version>/cli/<provider>/. This is the same path the frontend uses to launch the agent (agent-model.ts::resolveCliDir), so the bin we drop in node_modules/.bin/ is what the launch path will execute. Honors portable / installed mode + the AGENTMUX_HOME_OVERRIDE test override via DataPaths::from_env().

register_install_handlers

resolve_installed_bin 🔒

resolve_tool_path 🔒

Returns the path to the installed CLI binary if present in the per-version cache, else None. Used by install.check. Locate a system tool (e.g. git, gh) on PATH. Uses the platform equivalent of which and returns the resolved absolute path. None when the tool isn’t on PATH or the lookup itself failed.

spawn_install_task 🔒