Merge pull request #10 from Agentiix/fix/runtime-env-injection-contract

Define runtime env injection contract

Author: FatPigeorz

agentix/nix/Dockerfile

@@ -30,7 +30,23 @@ WORKDIR /build
 # nix build (toolchain + runtime), uv venv + uv sync, closure discovery.
 RUN sh ./bundle-build.sh
 
-ENV PATH="/nix/runtime/bin:/nix/runtime/venv/bin:${PATH}" \
+ENV PATH="/nix/runtime/venv/bin:/nix/runtime/bin:${PATH}" \
+    LD_LIBRARY_PATH="/nix/runtime/lib" \
+    LIBRARY_PATH="/nix/runtime/lib" \
+    CPATH="/nix/runtime/include" \
+    C_INCLUDE_PATH="/nix/runtime/include" \
+    CPLUS_INCLUDE_PATH="/nix/runtime/include" \
+    PKG_CONFIG_PATH="/nix/runtime/lib/pkgconfig:/nix/runtime/share/pkgconfig" \
+    CMAKE_PREFIX_PATH="/nix/runtime" \
+    AGENTIX_ADDED_PATH="/nix/runtime/venv/bin:/nix/runtime/bin" \
+    AGENTIX_ADDED_LD_LIBRARY_PATH="/nix/runtime/lib" \
+    AGENTIX_ADDED_LIBRARY_PATH="/nix/runtime/lib" \
+    AGENTIX_ADDED_CPATH="/nix/runtime/include" \
+    AGENTIX_ADDED_C_INCLUDE_PATH="/nix/runtime/include" \
+    AGENTIX_ADDED_CPLUS_INCLUDE_PATH="/nix/runtime/include" \
+    AGENTIX_ADDED_PKG_CONFIG_PATH="/nix/runtime/lib/pkgconfig:/nix/runtime/share/pkgconfig" \
+    AGENTIX_ADDED_CMAKE_PREFIX_PATH="/nix/runtime" \
     AGENTIX_BIND_PORT=8000
 EXPOSE 8000/tcp
+VOLUME ["/nix"]
 ENTRYPOINT ["/nix/runtime/venv/bin/agentix-server"]

agentix/runtime/env.py

@@ -0,0 +1,74 @@
+"""Runtime environment helpers.
+
+Agentix may prepend bundle-owned paths while booting the runtime or its
+worker. User-facing subprocesses should be able to run without those
+bundle paths leaking into normal command lookup.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+AGENTIX_ADDED_PATH = "AGENTIX_ADDED_PATH"
+AGENTIX_ADDED_LD_LIBRARY_PATH = "AGENTIX_ADDED_LD_LIBRARY_PATH"
+
+_TRACKING_PREFIX = "AGENTIX_ADDED_"
+
+
+def _split_path(value: str) -> list[str]:
+    return value.split(os.pathsep) if value else []
+
+
+def _remove_path_entries(value: str, entries: str) -> str:
+    remove = set(_split_path(entries))
+    if not remove:
+        return value
+    return os.pathsep.join(entry for entry in _split_path(value) if entry not in remove)
+
+
+def _target_var(tracking_var: str) -> str | None:
+    if not tracking_var.startswith(_TRACKING_PREFIX):
+        return None
+    name = tracking_var.removeprefix(_TRACKING_PREFIX)
+    return name or None
+
+
+def get_env_without_agentix(
+    extra: Mapping[str, str] | None = None,
+    *,
+    base: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Return an environment for user subprocesses without Agentix-added paths.
+
+    The helper only subtracts entries that Agentix explicitly recorded in
+    `AGENTIX_ADDED_*`. It intentionally does not remove arbitrary `/nix`
+    paths, because a task image may itself be Nix-based.
+    """
+
+    env = dict(os.environ if base is None else base)
+
+    tracking_vars = [name for name in env if name.startswith(_TRACKING_PREFIX)]
+    for tracking_var in tracking_vars:
+        target = _target_var(tracking_var)
+        if target is None:
+            continue
+        value = _remove_path_entries(env.get(target, ""), env.get(tracking_var, ""))
+        if value:
+            env[target] = value
+        else:
+            env.pop(target, None)
+
+    for name in tracking_vars:
+        env.pop(name, None)
+
+    if extra:
+        env.update(extra)
+    return env
+
+
+__all__ = [
+    "AGENTIX_ADDED_LD_LIBRARY_PATH",
+    "AGENTIX_ADDED_PATH",
+    "get_env_without_agentix",
+]

agentix/runtime/server/worker/client.py

@@ -18,6 +18,7 @@
 from pathlib import Path
 from typing import Any, Protocol
 
+from agentix.runtime.env import AGENTIX_ADDED_PATH
 from agentix.runtime.server.worker.invoker import CallableInvoker
 from agentix.runtime.shared.framing import read_frame, write_frame
 from agentix.runtime.shared.models import RemoteError, RemoteRequest, RemoteResponse
@@ -44,15 +45,28 @@
 # (`subprocess.run("claude", ...)`, `c.remote(cc.run, ...)`, ...) must
 # be able to find those binaries by bare name.
 _RUNTIME_BIN_PATH = "/nix/runtime/bin"
+_RUNTIME_LIB_PATH = "/nix/runtime/lib"
+_RUNTIME_INCLUDE_PATH = "/nix/runtime/include"
 _STRIPPED_ENV = {
-    "LD_LIBRARY_PATH",
     "LD_PRELOAD",
     "PYTHONPATH",
     "PYTHONHOME",
     "LOCALE_ARCHIVE",
     "SSL_CERT_FILE",
 }
 _STRIPPED_ENV_PREFIXES = ("NIX_", "FONTCONFIG_")
+_RUNTIME_PATH_ADDITIONS = {
+    "LD_LIBRARY_PATH": (_RUNTIME_LIB_PATH,),
+    "LIBRARY_PATH": (_RUNTIME_LIB_PATH,),
+    "CPATH": (_RUNTIME_INCLUDE_PATH,),
+    "C_INCLUDE_PATH": (_RUNTIME_INCLUDE_PATH,),
+    "CPLUS_INCLUDE_PATH": (_RUNTIME_INCLUDE_PATH,),
+    "PKG_CONFIG_PATH": (
+        "/nix/runtime/lib/pkgconfig",
+        "/nix/runtime/share/pkgconfig",
+    ),
+    "CMAKE_PREFIX_PATH": ("/nix/runtime",),
+}
 
 
 def _join_path_entries(entries: Iterable[str]) -> str:
@@ -66,6 +80,17 @@ def _join_path_entries(entries: Iterable[str]) -> str:
     return os.pathsep.join(parts)
 
 
+def _tracking_var(name: str) -> str:
+    return f"AGENTIX_ADDED_{name}"
+
+
+def _prepend_recorded_path_entries(env: dict[str, str], name: str, entries: Iterable[str]) -> None:
+    added = _join_path_entries(entries)
+    env[name] = _join_path_entries([*added.split(os.pathsep), *env.get(name, "").split(os.pathsep)])
+    tracking_name = _tracking_var(name)
+    env[tracking_name] = _join_path_entries([*env.get(tracking_name, "").split(os.pathsep), *added.split(os.pathsep)])
+
+
 def _clean_worker_env(runtime_bin_dir: Path | None) -> dict[str, str]:
     env = {
         key: value
@@ -82,6 +107,16 @@ def _clean_worker_env(runtime_bin_dir: Path | None) -> dict[str, str]:
     parts.append(_RUNTIME_BIN_PATH)
     parts.extend(env.get("PATH", "").split(os.pathsep))
     env["PATH"] = _join_path_entries(parts)
+
+    added_path = []
+    added_path.extend(env.get(AGENTIX_ADDED_PATH, "").split(os.pathsep))
+    if runtime_bin_dir is not None:
+        added_path.append(str(runtime_bin_dir))
+    added_path.append(_RUNTIME_BIN_PATH)
+    env[AGENTIX_ADDED_PATH] = _join_path_entries(added_path)
+
+    for name, entries in _RUNTIME_PATH_ADDITIONS.items():
+        _prepend_recorded_path_entries(env, name, entries)
     return env
 
 

plugins/deployment-docker/agentix/deployment/docker.py

@@ -26,8 +26,8 @@
       docker run [--platform <platform>] -d --name <sid> --network host \\
          -e AGENTIX_BIND_PORT=<port> \\
          --volumes-from <carrier>:ro \\
-         --entrypoint /nix/runtime/bin/agentix-server \\
-         <image>
+         --entrypoint /bin/sh \\
+         <image> -c '<inject runtime env; exec agentix-server>'
 
   `agentix-server` binds to the port from `AGENTIX_BIND_PORT`. We pick
   a free host port, pass it through, and health-check `/health` on it.
@@ -47,7 +47,36 @@
 
 logger = logging.getLogger("agentix.deployment.docker")
 
-_RUNTIME_ENTRYPOINT = "/nix/runtime/bin/agentix-server"
+_RUNTIME_ENTRYPOINT = "/bin/sh"
+_RUNTIME_BOOTSTRAP = r"""
+set -eu
+agentix_prepend_path() {
+  name="$1"
+  added="$2"
+  tracking="AGENTIX_ADDED_${name}"
+  eval "current=\${$name-}"
+  eval "tracked=\${$tracking-}"
+  if [ -n "$current" ]; then
+    export "$name=$added:$current"
+  else
+    export "$name=$added"
+  fi
+  if [ -n "$tracked" ]; then
+    export "$tracking=$tracked:$added"
+  else
+    export "$tracking=$added"
+  fi
+}
+agentix_prepend_path PATH "/nix/runtime/venv/bin:/nix/runtime/bin"
+agentix_prepend_path LD_LIBRARY_PATH "/nix/runtime/lib"
+agentix_prepend_path LIBRARY_PATH "/nix/runtime/lib"
+agentix_prepend_path CPATH "/nix/runtime/include"
+agentix_prepend_path C_INCLUDE_PATH "/nix/runtime/include"
+agentix_prepend_path CPLUS_INCLUDE_PATH "/nix/runtime/include"
+agentix_prepend_path PKG_CONFIG_PATH "/nix/runtime/lib/pkgconfig:/nix/runtime/share/pkgconfig"
+agentix_prepend_path CMAKE_PREFIX_PATH "/nix/runtime"
+exec /nix/runtime/venv/bin/agentix-server
+""".strip()
 
 
 async def _docker(*args: str, check: bool = True) -> tuple[int, bytes, bytes]:
@@ -120,6 +149,7 @@ async def create(self, config: SandboxConfig) -> Sandbox:
             "--volumes-from", f"{carrier}:ro",
             "--entrypoint", _RUNTIME_ENTRYPOINT,
             config.image,
+            "-c", _RUNTIME_BOOTSTRAP,
         )
 
         self._ports[sandbox_id] = port

plugins/runtime-basic/agentix/bash/__init__.py

@@ -27,42 +27,32 @@
 
 import asyncio
 import os
+import shutil
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from typing import Annotated, Literal
 
 from pydantic import Field
 
-# Env vars stripped before forking a user-space subprocess. The runtime
-# is a Nix-built binary; os.environ is pre-loaded with Nix runtime paths
-# (LD_LIBRARY_PATH pointing at Nix-store libs, NIX_*, PYTHONPATH,
-# FONTCONFIG_*). Leaking those into a host-image subprocess causes glibc
-# ABI mismatches and silent library override bugs.
-_RUNTIME_ONLY_ENV = {
-    "LD_LIBRARY_PATH",
-    "LD_PRELOAD",
-    "PYTHONPATH",
-    "PYTHONHOME",
-    "LOCALE_ARCHIVE",
-    "FONTCONFIG_FILE",
-    "FONTCONFIG_PATH",
-    "SSL_CERT_FILE",
-    "NIX_SSL_CERT_FILE",
-}
+_BUNDLE_BASH = "/nix/runtime/bin/bash"
 
 
 def _clean_env(extra: dict[str, str] | None) -> dict[str, str]:
-    """Build a subprocess env: scrubbed base + caller overrides."""
-    env = {
-        k: v
-        for k, v in os.environ.items()
-        if k not in _RUNTIME_ONLY_ENV and not k.startswith("NIX_")
-    }
+    """Build a subprocess env: inherited runtime env + caller overrides."""
+    env = dict(os.environ)
     if extra:
         env.update(extra)
     return env
 
 
+def _shell_executable(executable: str | None, env: dict[str, str]) -> str:
+    if executable:
+        return shutil.which(executable, path=env.get("PATH")) or executable
+    if os.access(_BUNDLE_BASH, os.X_OK):
+        return _BUNDLE_BASH
+    return shutil.which("bash", path=env.get("PATH")) or "/bin/bash"
+
+
 async def _read_capped(stream: asyncio.StreamReader, limit: int) -> str:
     """Drain a subprocess stream, retaining at most `limit` bytes.
 
@@ -155,6 +145,7 @@ async def run(
     env: dict[str, str] | None = None,
     timeout: float | None = None,
     max_output: int = 10 * 1024 * 1024,
+    executable: str | None = None,
 ) -> BashResult:
     """Run a shell command in the sandbox and return its captured output."""
     sub_env = _clean_env(env)
@@ -164,6 +155,7 @@ async def run(
         stderr=asyncio.subprocess.PIPE,
         cwd=cwd,
         env=sub_env,
+        executable=_shell_executable(executable, sub_env),
     )
     assert proc.stdout is not None and proc.stderr is not None
     stdout_task = asyncio.create_task(_read_capped(proc.stdout, max_output))
@@ -193,6 +185,7 @@ async def run_stream(
     cwd: str | None = None,
     env: dict[str, str] | None = None,
     timeout: float | None = None,
+    executable: str | None = None,
 ) -> AsyncIterator[BashEvent]:
     """Run a shell command, yielding events as the subprocess emits them.
 
@@ -206,6 +199,7 @@ async def run_stream(
         stderr=asyncio.subprocess.PIPE,
         cwd=cwd,
         env=sub_env,
+        executable=_shell_executable(executable, sub_env),
     )
 
     async def _pump(stream, tag, queue):

plugins/runtime-basic/tests/test_primitives.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
+import os
 import shlex
 import sys
+from pathlib import Path
 
 import agentix.bash as bash
 import agentix.files as files
@@ -46,3 +48,69 @@ async def test_bash_run_drains_stderr_after_output_cap():
     assert result.exit_code == 0
     assert result.stdout.strip() == "done"
     assert "[truncated at 1024 bytes]" in result.stderr
+
+
+@pytest.mark.asyncio
+async def test_bash_run_honors_bash_env(tmp_path: Path):
+    bash_env = tmp_path / "bash_env"
+    bash_env.write_text("export FROM_BASH_ENV=loaded\n")
+
+    result = await bash.run(
+        "printf '%s' \"$FROM_BASH_ENV\"",
+        env={"BASH_ENV": str(bash_env)},
+    )
+
+    assert result.exit_code == 0
+    assert result.stdout == "loaded"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("executable", ["bash", "zsh", "fish"])
+async def test_bash_run_can_use_explicit_executable_names(tmp_path: Path, executable: str):
+    fakebin = tmp_path / "bin"
+    fakebin.mkdir()
+    shell_path = fakebin / executable
+    shell_path.write_text(
+        "#!/bin/sh\n"
+        "if [ \"$1\" != \"-c\" ]; then exit 64; fi\n"
+        "shift\n"
+        "export AGENTIX_TEST_SHELL=\"$(basename \"$0\")\"\n"
+        "exec /bin/sh -c \"$1\"\n"
+    )
+    shell_path.chmod(0o755)
+
+    result = await bash.run(
+        "printf '%s' \"$AGENTIX_TEST_SHELL\"",
+        env={"PATH": os.pathsep.join([str(fakebin), os.environ.get("PATH", "")])},
+        executable=executable,
+    )
+
+    assert result.exit_code == 0
+    assert result.stdout == executable
+
+
+@pytest.mark.asyncio
+async def test_bash_run_stream_can_use_explicit_executable(tmp_path: Path):
+    fakebin = tmp_path / "bin"
+    fakebin.mkdir()
+    shell_path = fakebin / "zsh"
+    shell_path.write_text(
+        "#!/bin/sh\n"
+        "if [ \"$1\" != \"-c\" ]; then exit 64; fi\n"
+        "shift\n"
+        "export AGENTIX_TEST_SHELL=\"$(basename \"$0\")\"\n"
+        "exec /bin/sh -c \"$1\"\n"
+    )
+    shell_path.chmod(0o755)
+
+    events = [
+        event
+        async for event in bash.run_stream(
+            "printf '%s' \"$AGENTIX_TEST_SHELL\"",
+            env={"PATH": os.pathsep.join([str(fakebin), os.environ.get("PATH", "")])},
+            executable="zsh",
+        )
+    ]
+
+    assert [event.data for event in events if isinstance(event, bash.BashStdout)] == ["zsh"]
+    assert [event.exit_code for event in events if isinstance(event, bash.BashExit)] == [0]