agentix-runtime-basic 0.1.1__py3-none-any.whl

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/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.1.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: agentix-runtime-basic
+Version: 0.1.1
+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: agentixx>=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.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+agentix/bash/__init__.py,sha256=n39E5fT_ObemG5zYUOH1y9xMK1hnWMIyM9y9cSq58c8,8176
+agentix/files/__init__.py,sha256=54kyYKLE2-wI9Eu_fC9lOSNUmP1AetRjDwgjumdQLxI,4846
+agentix_runtime_basic-0.1.1.dist-info/METADATA,sha256=_0MYs4i4tdo4M-Lsfi2iMN4zV0klJlf7n0-hz8SYDOc,2102
+agentix_runtime_basic-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentix_runtime_basic-0.1.1.dist-info/entry_points.txt,sha256=yBKDuZJEX0Vi-e-CmwLijw5VmZn3puPBlx3gflhtzfg,62
+agentix_runtime_basic-0.1.1.dist-info/licenses/LICENSE,sha256=mt35xkyIDkKZlEgxp-WYN0zaNDhtZtYtagSi6rMQmXg,1065
+agentix_runtime_basic-0.1.1.dist-info/RECORD,,

agentix_runtime_basic-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentix_runtime_basic-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[agentix.namespace]
+bash = agentix.bash
+files = agentix.files

agentix_runtime_basic-0.1.1.dist-info/licenses/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.