agentix-runtime-basic 0.1.0__tar.gz

agentix_runtime_basic-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+
+.vscode/
+.idea/
+.DS_Store

agentix_runtime_basic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentiix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentix_runtime_basic-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: agentix-runtime-basic
+Version: 0.1.0
+Summary: Shell + file I/O primitives for Agentix sandboxes
+Project-URL: Homepage, https://github.com/Agentiix/Agentix-Runtime-Basic
+Author: Agentiix
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: agentix>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentix-runtime-basic
+
+Shell + file I/O primitives for [Agentix](https://github.com/Agentiix/Agentix)
+sandboxes. One wheel, two namespaces:
+
+| Namespace | Purpose |
+|---|---|
+| `agentix.bash` | execute shell commands, stream stdout/stderr |
+| `agentix.files` | upload/download/list files inside the sandbox |
+
+These two used to ship as separate `agentix-bash` and `agentix-files`
+distributions. They consolidated here because every realistic sandbox
+image needs both — splitting them was friction without isolation
+benefit (neither has any non-stdlib runtime deps).
+
+## Install
+
+```bash
+pip install agentix-runtime-basic
+```
+
+## Use
+
+```python
+from agentix import RuntimeClient
+from agentix.bash import run as bash_run, run_stream as bash_stream
+from agentix.files import upload, download
+
+async with RuntimeClient(sandbox.runtime_url) as c:
+    await c.remote(upload, path="data.json", content=blob)
+    result = await c.remote(bash_run, command="cat data.json | jq .")
+    async for ev in c.remote(bash_stream, command="pytest -q"):
+        ...  # ev is a BashStdout / BashStderr / BashExit / BashError
+```
+
+Each namespace is "the package IS the namespace": top-level async
+functions are the remote-callable surface, dataclasses/types like
+`BashResult` and `UploadResult` are importable for return-type
+annotations.
+
+## Building a sandbox image
+
+`runtime/Dockerfile` is the base image bundle builds extend from. Most
+users invoke it indirectly:
+
+```bash
+agentix build runtime-basic -o my-agent:0.1.0
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agentix_runtime_basic-0.1.0/README.md

@@ -0,0 +1,52 @@
+# agentix-runtime-basic
+
+Shell + file I/O primitives for [Agentix](https://github.com/Agentiix/Agentix)
+sandboxes. One wheel, two namespaces:
+
+| Namespace | Purpose |
+|---|---|
+| `agentix.bash` | execute shell commands, stream stdout/stderr |
+| `agentix.files` | upload/download/list files inside the sandbox |
+
+These two used to ship as separate `agentix-bash` and `agentix-files`
+distributions. They consolidated here because every realistic sandbox
+image needs both — splitting them was friction without isolation
+benefit (neither has any non-stdlib runtime deps).
+
+## Install
+
+```bash
+pip install agentix-runtime-basic
+```
+
+## Use
+
+```python
+from agentix import RuntimeClient
+from agentix.bash import run as bash_run, run_stream as bash_stream
+from agentix.files import upload, download
+
+async with RuntimeClient(sandbox.runtime_url) as c:
+    await c.remote(upload, path="data.json", content=blob)
+    result = await c.remote(bash_run, command="cat data.json | jq .")
+    async for ev in c.remote(bash_stream, command="pytest -q"):
+        ...  # ev is a BashStdout / BashStderr / BashExit / BashError
+```
+
+Each namespace is "the package IS the namespace": top-level async
+functions are the remote-callable surface, dataclasses/types like
+`BashResult` and `UploadResult` are importable for return-type
+annotations.
+
+## Building a sandbox image
+
+`runtime/Dockerfile` is the base image bundle builds extend from. Most
+users invoke it indirectly:
+
+```bash
+agentix build runtime-basic -o my-agent:0.1.0
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agentix_runtime_basic-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentix-runtime-basic"
+version = "0.1.0"
+description = "Shell + file I/O primitives for Agentix sandboxes"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Agentiix" }]
+urls = { Homepage = "https://github.com/Agentiix/Agentix-Runtime-Basic" }
+dependencies = [
+    # Both namespaces are pure-stdlib at runtime; the framework dep is
+    # only here so `pip install agentix-runtime-basic` brings agentix
+    # along as a peer (entry-point discovery needs the framework
+    # installed in the same venv).
+    "agentix>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "pyright>=1.1.380",
+]
+
+# Two namespaces shipped from one wheel. Both register under
+# `agentix.namespace`; the framework spawns one worker subprocess per
+# namespace from the same venv. Splitting them was previously two
+# wheels (agentix-bash + agentix-files) — they're consolidated here
+# because they share dependencies (none beyond the stdlib + agentix)
+# and a deployment lifecycle (every sandbox image needs both).
+[project.entry-points."agentix.namespace"]
+bash = "agentix.bash"
+files = "agentix.files"
+
+[tool.hatch.build.targets.wheel]
+# `src/agentix/` is a PEP 420 namespace package (no __init__.py);
+# hatchling walks the tree and installs files at `agentix/bash/` and
+# `agentix/files/` in the wheel.
+packages = ["src/agentix"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__", ".venv"]
+typeCheckingMode = "basic"
+pythonVersion = "3.11"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

agentix_runtime_basic-0.1.0/runtime/Dockerfile

@@ -0,0 +1,40 @@
+# Runtime image — Python slim + framework venv + uv.
+#
+# `agentix build` auto-builds this image (from the repo root) when it's
+# missing locally. You don't normally run `docker build` directly.
+#
+# The runtime image carries:
+#   /nix/runtime/          — framework venv (uv-managed); ENTRYPOINT runs from here
+#   /nix/.wheels/          — the framework wheel, stashed for bundle stages to reuse
+#   uv on $PATH            — used by `agentix build`'s generated Dockerfile to
+#                            create one venv per namespace at /nix/<short>/
+#
+# Namespace bundles extend this image: each namespace gets `/nix/<short>/`
+# with its own uv venv + (optional) Nix sys-deps symlinked into bin/.
+# The multiplexer spawns one worker subprocess per namespace using that
+# namespace's interpreter and prepends `/nix/<short>/bin` to PATH so
+# `subprocess.run("git", ...)` in user code resolves transparently.
+
+FROM python:3.11-slim AS builder
+WORKDIR /build
+RUN pip install --no-cache-dir build
+COPY pyproject.toml README.md ./
+COPY agentix ./agentix
+RUN python -m build --wheel --outdir /dist
+
+FROM python:3.11-slim
+RUN pip install --no-cache-dir uv
+
+# Framework wheel — kept so each bundled namespace's venv can install it
+# without reaching PyPI.
+RUN mkdir -p /nix/.wheels
+COPY --from=builder /dist/*.whl /nix/.wheels/
+
+# Runtime's own venv. /nix/runtime owns the framework dispatcher;
+# the multiplexer is what spawns per-namespace workers.
+RUN uv venv /nix/runtime && \
+    /nix/runtime/bin/pip install --no-cache-dir /nix/.wheels/agentix-*.whl
+
+EXPOSE 8000
+ENV AGENTIX_BIND_PORT=8000
+ENTRYPOINT ["/nix/runtime/bin/agentix-server"]

agentix_runtime_basic-0.1.0/src/agentix/bash/__init__.py

@@ -0,0 +1,260 @@
+"""Bash primitive — shell command execution as an Agentix namespace.
+
+Usage:
+
+    from agentix import RuntimeClient
+    from agentix import bash
+    from agentix.bash import BashStdout, BashStderr, BashExit, BashError
+
+    async with RuntimeClient(sandbox.runtime_url) as c:
+        r = await c.remote(bash.run, command="ls -la", cwd="/workspace")
+        print(r.exit_code, r.stdout)
+
+        async for ev in c.remote(bash.run_stream, command="long-job.sh"):
+            match ev:
+                case BashStdout(data=chunk): print(chunk, end="")
+                case BashStderr(data=chunk): print(chunk, end="")
+                case BashExit(exit_code=code): print(f"\\nexit {code}")
+                case BashError(message=msg): print(f"\\nerror: {msg}")
+
+The package IS the namespace — `run` and `run_stream` are top-level
+async functions, dataclasses (`BashResult`, `BashStdout`, …) coexist
+as types callers can import. The framework's discovery picks the async
+functions; types and constants are just regular Python imports.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+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",
+}
+
+
+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_")
+    }
+    if extra:
+        env.update(extra)
+    return env
+
+
+async def _read_capped(stream: asyncio.StreamReader, limit: int) -> str:
+    """Drain a subprocess stream, retaining at most `limit` bytes.
+
+    The drain-to-EOF part matters: if one pipe stops being read after its cap
+    is reached, the child can block forever writing to that full pipe while the
+    parent waits on the process.
+    """
+    chunks: list[bytes] = []
+    total = 0
+    truncated = False
+    while True:
+        chunk = await stream.read(8192)
+        if not chunk:
+            break
+        remaining = limit - total
+        if remaining <= 0:
+            truncated = True
+            continue
+        if len(chunk) >= remaining:
+            chunks.append(chunk[:remaining])
+            truncated = len(chunk) > remaining
+            total = limit
+            continue
+        chunks.append(chunk)
+        total += len(chunk)
+    if truncated:
+        chunks.append(b"\n[truncated at %d bytes]" % limit)
+    return b"".join(chunks).decode(errors="replace")
+
+
+@dataclass
+class BashResult:
+    """Return value of `Bash.run` — full output captured before the call returns."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+# Algebraic stream events — each variant is its own dataclass so callers
+# can `match event: case BashStdout(...)` and pyright tracks the type.
+# The `type` field is the wire discriminator; users pattern-match the
+# class, not the field.
+
+
+@dataclass
+class BashStdout:
+    """A chunk of subprocess stdout."""
+
+    data: str
+    type: Literal["stdout"] = "stdout"
+
+
+@dataclass
+class BashStderr:
+    """A chunk of subprocess stderr."""
+
+    data: str
+    type: Literal["stderr"] = "stderr"
+
+
+@dataclass
+class BashExit:
+    """The subprocess finished. `exit_code` is its return status."""
+
+    exit_code: int
+    type: Literal["exit"] = "exit"
+
+
+@dataclass
+class BashError:
+    """Wire-side problem (e.g. timeout, fork failure). `message` explains."""
+
+    message: str
+    type: Literal["error"] = "error"
+
+
+BashEvent = Annotated[
+    BashStdout | BashStderr | BashExit | BashError,
+    Field(discriminator="type"),
+]
+"""One event from `Bash.run_stream`. Discriminated union of the four
+variants above — JSON wire form carries a `type` tag, but in Python
+the user pattern-matches the class directly."""
+
+
+async def run(
+    command: str,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+    timeout: float | None = None,
+    max_output: int = 10 * 1024 * 1024,
+) -> BashResult:
+    """Run a shell command in the sandbox and return its captured output."""
+    sub_env = _clean_env(env)
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=cwd,
+        env=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))
+    stderr_task = asyncio.create_task(_read_capped(proc.stderr, max_output))
+    wait_task = asyncio.create_task(proc.wait())
+    try:
+        await asyncio.wait_for(
+            asyncio.gather(stdout_task, stderr_task, wait_task),
+            timeout=timeout,
+        )
+    except TimeoutError:
+        proc.kill()
+        await proc.wait()
+        for task in (stdout_task, stderr_task):
+            task.cancel()
+        await asyncio.gather(stdout_task, stderr_task, return_exceptions=True)
+        return BashResult(
+            exit_code=-1, stdout="", stderr=f"Command timed out after {timeout}s",
+        )
+    stdout = stdout_task.result()
+    stderr = stderr_task.result()
+    return BashResult(exit_code=proc.returncode or 0, stdout=stdout, stderr=stderr)
+
+
+async def run_stream(
+    command: str,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+    timeout: float | None = None,
+) -> AsyncIterator[BashEvent]:
+    """Run a shell command, yielding events as the subprocess emits them.
+
+    Terminates with a single `BashExit` event on normal completion or
+    a single `BashError` event on timeout / wire-level failure.
+    """
+    sub_env = _clean_env(env)
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=cwd,
+        env=sub_env,
+    )
+
+    async def _pump(stream, tag, queue):
+        while True:
+            chunk = await stream.read(4096)
+            if not chunk:
+                break
+            await queue.put((tag, chunk))
+        await queue.put((tag, None))
+
+    queue: asyncio.Queue = asyncio.Queue()
+    tasks = [
+        asyncio.create_task(_pump(proc.stdout, "stdout", queue)),
+        asyncio.create_task(_pump(proc.stderr, "stderr", queue)),
+    ]
+    open_streams = {"stdout", "stderr"}
+
+    try:
+        deadline = None
+        if timeout is not None:
+            deadline = asyncio.get_event_loop().time() + timeout
+        while open_streams:
+            remaining = None
+            if deadline is not None:
+                remaining = max(deadline - asyncio.get_event_loop().time(), 0)
+                if remaining == 0:
+                    proc.kill()
+                    yield BashError(message=f"Command timed out after {timeout}s")
+                    return
+            try:
+                tag, chunk = await asyncio.wait_for(queue.get(), timeout=remaining)
+            except TimeoutError:
+                proc.kill()
+                yield BashError(message=f"Command timed out after {timeout}s")
+                return
+            if chunk is None:
+                open_streams.discard(tag)
+                continue
+            text = chunk.decode(errors="replace")
+            if tag == "stdout":
+                yield BashStdout(data=text)
+            else:
+                yield BashStderr(data=text)
+        await proc.wait()
+        yield BashExit(exit_code=proc.returncode or 0)
+    finally:
+        for t in tasks:
+            t.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        if proc.returncode is None:
+            proc.kill()
+            await proc.wait()

agentix_runtime_basic-0.1.0/src/agentix/files/__init__.py

@@ -0,0 +1,145 @@
+"""Files primitive — sandbox file upload / download as an Agentix namespace.
+
+Usage:
+
+    from agentix import RuntimeClient
+    from agentix import files
+
+    async with RuntimeClient(sandbox.runtime_url) as c:
+        r = await c.remote(files.upload, path="/workspace/input.txt", content=b"hello")
+        print(r.size)
+
+        data = await c.remote(files.download, path="/workspace/output.txt")
+
+Files are encoded as pydantic `bytes` (base64 in the JSON wire form).
+Suitable for kB–MB sized files; very large blobs should ship via a
+purpose-built binary `WirePattern` rather than the unary JSON path.
+
+The package IS the namespace — `upload` and `download` are top-level
+async functions, `UploadResult` is a regular dataclass callers can
+import for type hints.
+
+Writes/reads are confined to `$AGENTIX_UPLOAD_ROOT` (default
+`/workspace`). Paths outside that root raise `PermissionError`.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+UPLOAD_ROOT = Path(os.environ.get("AGENTIX_UPLOAD_ROOT", "/workspace")).resolve()
+
+
+@dataclass
+class UploadResult:
+    """What `upload` returns — resolved sandbox-side path + bytes written."""
+
+    path: str
+    size: int
+
+
+def _resolve_within(path: str) -> Path:
+    """Return `path` lexically under `UPLOAD_ROOT`.
+
+    Actual open/read/write calls below walk from an already-open root
+    directory fd with O_NOFOLLOW, so symlink swaps cannot redirect the
+    final file operation outside the upload root.
+    """
+    return UPLOAD_ROOT / Path(*_relative_parts(path))
+
+
+def _relative_parts(path: str) -> tuple[str, ...]:
+    raw = os.path.normpath(path)
+    if os.path.isabs(raw):
+        root = os.fspath(UPLOAD_ROOT)
+        try:
+            if os.path.commonpath([root, raw]) != root:
+                raise PermissionError(f"Path {raw} outside allowed root {UPLOAD_ROOT}")
+        except ValueError as exc:
+            raise PermissionError(f"Path {raw} outside allowed root {UPLOAD_ROOT}") from exc
+        raw = os.path.relpath(raw, root)
+    parts = tuple(p for p in Path(raw).parts if p not in ("", "."))
+    if not parts or any(p == ".." for p in parts):
+        raise PermissionError(f"Path {path!r} outside allowed root {UPLOAD_ROOT}")
+    return parts
+
+
+def _open_parent(parts: tuple[str, ...], *, create: bool) -> tuple[int, str]:
+    """Open the parent directory under UPLOAD_ROOT without following symlinks.
+
+    Returns `(parent_fd, filename)`. The caller owns `parent_fd`.
+    """
+    root_fd = os.open(UPLOAD_ROOT, os.O_RDONLY | os.O_DIRECTORY)
+    fd = root_fd
+    try:
+        for part in parts[:-1]:
+            if create:
+                try:
+                    os.mkdir(part, mode=0o777, dir_fd=fd)
+                except FileExistsError:
+                    pass
+            try:
+                next_fd = os.open(
+                    part,
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                    dir_fd=fd,
+                )
+            except OSError as exc:
+                if exc.errno == errno.ELOOP:
+                    raise PermissionError(
+                        f"Refusing to follow symlink inside {UPLOAD_ROOT}"
+                    ) from exc
+                raise
+            os.close(fd)
+            fd = next_fd
+        return fd, parts[-1]
+    except Exception:
+        os.close(fd)
+        raise
+
+
+def _open_file(path: str, flags: int, *, create_parents: bool, mode: int = 0o666) -> tuple[int, Path]:
+    parts = _relative_parts(path)
+    parent_fd, name = _open_parent(parts, create=create_parents)
+    try:
+        try:
+            fd = os.open(name, flags | os.O_NOFOLLOW, mode, dir_fd=parent_fd)
+        except OSError as exc:
+            if exc.errno == errno.ELOOP:
+                raise PermissionError(
+                    f"Refusing to follow symlink inside {UPLOAD_ROOT}"
+                ) from exc
+            raise
+        return fd, _resolve_within(path)
+    finally:
+        os.close(parent_fd)
+
+
+async def upload(path: str, content: bytes) -> UploadResult:
+    """Write `content` to `path` inside the sandbox.
+
+    Creates parent directories as needed. `path` must resolve under
+    the upload-root; otherwise raises `PermissionError`.
+    """
+    fd, p = _open_file(
+        path,
+        os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+        create_parents=True,
+    )
+    with os.fdopen(fd, "wb") as f:
+        f.write(content)
+    return UploadResult(path=str(p), size=len(content))
+
+
+async def download(path: str) -> bytes:
+    """Read the contents of `path` from inside the sandbox.
+
+    Raises `FileNotFoundError` / `IsADirectoryError` /
+    `PermissionError` for the corresponding filesystem conditions.
+    """
+    fd, _ = _open_file(path, os.O_RDONLY, create_parents=False)
+    with os.fdopen(fd, "rb") as f:
+        return f.read()

agentix_runtime_basic-0.1.0/tests/test_primitives.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import asyncio
+import shlex
+import sys
+
+import pytest
+
+import agentix.bash as bash
+import agentix.files as files
+
+
+@pytest.mark.asyncio
+async def test_files_upload_refuses_symlink_escape(tmp_path, monkeypatch):
+    outside = tmp_path / "outside.txt"
+    root = tmp_path / "workspace"
+    root.mkdir()
+    monkeypatch.setenv("AGENTIX_UPLOAD_ROOT", str(root))
+    # files reads UPLOAD_ROOT from env at import time; force a reload so
+    # the patched env takes effect for this test.
+    import importlib
+    importlib.reload(files)
+
+    link = root / "link"
+    link.symlink_to(outside)
+
+    with pytest.raises(PermissionError):
+        await files.upload(str(link), b"escape")
+    assert not outside.exists()
+
+
+@pytest.mark.asyncio
+async def test_bash_run_drains_stderr_after_output_cap():
+    code = (
+        "import sys; "
+        "sys.stderr.write('x' * 200000); "
+        "sys.stderr.flush(); "
+        "print('done')"
+    )
+    command = f"{shlex.quote(sys.executable)} -c {shlex.quote(code)}"
+
+    result = await asyncio.wait_for(
+        bash.run(command, max_output=1024),
+        timeout=5,
+    )
+
+    assert result.exit_code == 0
+    assert result.stdout.strip() == "done"
+    assert "[truncated at 1024 bytes]" in result.stderr