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 MPS 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

InstallCancelResult

Result of install.cancel.

InstallCheckReq

InstallCheckResult

Result of install.check.

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

InstallStartResult

Result of install.start. Was an inline json!({ "sessionId": .. }).

PrereqToolResolution

One tool’s resolution in resolve.prereqs.

ResolvePrereqsReq

Request for resolve.prereqs. Was a function-local anonymous struct.

ResolvePrereqsResult

Result of resolve.prereqs.

Enums

InstallChunkEvent

install_chunk: one line of an install’s output, or its end. Scoped install:<sessionId>; system.install sends the same events.

InstallDoneOp

The op of the last event of an install.

InstallStream

Constants

COMMAND_INSTALL_CANCEL

COMMAND_INSTALL_CHECK

COMMAND_INSTALL_START

COMMAND_RESOLVE_PREREQS

INSTALL_LOG_TAIL_LINES 🔒

How many lines of npm output a failed install logs.

Functions

effective_pin 🔒

The pinned CLI version an install of provider_id uses: the backend provider registry’s pin (the source of truth), else the caller’s.

find_on_path 🔒

tool’s absolute path in the directories of path (a PATH-style list).

installed_bin_in 🔒

installed_dir_among 🔒

The first of dirs holding cli_command’s shim — the install a launch would use. Pure over dirs, for tests.

installed_version_in 🔒

Version of a managed provider install, read from the installed package’s own package.json. None for anything unreadable — a missing directory, a partial install, unparseable JSON — all of which mean “we do not know”, which is a distinct answer from “up to date” and must stay distinct.

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>/.

manifest_version 🔒

probe_prereq_version 🔒

Version of the prereq binary at path (already resolved on PATH), via --version, bounded so a hung binary can’t stall the launch check.

provider_install_dir 🔒

Where a new install of provider_id goes: the shared, pinned-version dir (backend::cli_install), which is also what resolvecli and the launch path look in first. Honors portable / installed mode + the AGENTMUX_HOME_OVERRIDE test override via DataPaths::from_env().

provider_installed_dirs 🔒

Every dir an existing install of provider_id may be in, in lookup order: the shared pinned-version dir, then the legacy per-AgentMux-version one.

push_tail 🔒

register_install_handlers

resolve_installed_dir 🔒

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 this process’s PATH and return its absolute path; None when it isn’t there.

spawn_install_task 🔒