Add user-writable bin directory to agent image PATH

Merged
KE
5mo ago
+93-10

What type of PR is this?

/kind feature

What this PR does / why we need it:

Issue #1151 asks Kelos to provide a writable directory on PATH so that
tools installed by Workspace.spec.setupCommand (e.g. pip install --user,
scripts dropped manually, go install) are resolvable by name from the agent
process that runs afterward.

Today, four of the five reference Dockerfiles (claude-code, codex,
gemini, opencode) only prepend /usr/local/go/bin and $GOPATH/bin to
PATH. The cursor image is the outlier — it already prepends
/home/agent/.local/bin. So a user running pip install --user some-tool
inside setupCommand on, say, the codex image cannot invoke some-tool
by name in their agent prompt.

This PR aligns all reference images on the convention of having
$HOME/.local/bin (the XDG / PEP 370 user-install location) on PATH:

  • Pre-create $HOME/.local/bin, owned by the agent user, in all five
    reference Dockerfiles.
  • Prepend $HOME/.local/bin to PATH in claude-code, codex, gemini,
    and opencode (cursor already had it; only its mkdir line was aligned
    for consistency).
  • Document the requirement in docs/agent-image-interface.md as a new
    section under "Requirements" so custom agent images follow the same
    contract.
  • Add an e2e case under Workspace setupCommand that installs a script
    into $HOME/.local/bin from setupCommand and verifies the agent
    resolves it via PATH.

Which issue(s) this PR is related to:

Fixes #1151

Special notes for your reviewer:

The convention chosen is $HOME/.local/bin because it matches what user-level
package managers already install into without configuration:

  • pip install --user
  • npm config set prefix ~/.local (then npm install -g some-tool)
  • Many curl-bash installers default to $HOME/.local/bin

$GOPATH/bin remains on PATH for go install, so both Go and non-Go
user-installed tools are reachable.

Does this PR introduce a user-facing change?

Agent images now include $HOME/.local/bin on PATH, so tools installed by Workspace.spec.setupCommand (e.g. via pip install --user) can be invoked by name from the agent process. The agent image interface contract documents this requirement for custom images.