agentixx 0.1.0__py3-none-any.whl

agentix/__init__.py

@@ -0,0 +1,26 @@
+"""agentix — typed remote calls for sandboxed Python modules.
+
+Integration wheels may contribute modules under `agentix.<short>`
+(e.g. `agentix.bash`). Extending `agentix.__path__` lets those modules
+co-exist with the framework modules in this package.
+"""
+
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+from agentix.runtime.client import RemoteCallError, RuntimeClient
+from agentix.runtime.shared.rpc import Bidi, Channel, RemoteCall, Stream, Unary
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Bidi",
+    "Channel",
+    "RemoteCall",
+    "RemoteCallError",
+    "RuntimeClient",
+    "Stream",
+    "Unary",
+    "__version__",
+]

agentix/cli/__init__.py

@@ -0,0 +1,70 @@
+"""`agentix` command-line interface.
+
+The core CLI intentionally stays narrow: `agentix build` packages a
+project into a bundle image. Other workflows should expose their own
+`console_scripts` entry instead of expanding the central CLI.
+
+The CLI deliberately doesn't use argparse subparsers — argparse
+intercepts `--help` greedily at the root level, so `agentix build --help`
+would never reach `build`'s parser. Manual routing keeps each
+subcommand's `--help` intact.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import sys
+from collections.abc import Callable, Sequence
+
+# Built-in subcommands. Each value names the submodule under
+# `agentix.cli` whose `main(argv)` handles the verb.
+_COMMANDS: tuple[tuple[str, str], ...] = (
+    ("build", "agentix.cli.build"),
+)
+
+
+def _first_doc_line(obj: object) -> str:
+    """First non-empty line of an object's docstring, or empty."""
+    doc = inspect.getdoc(obj) or ""
+    return next((line.strip() for line in doc.splitlines() if line.strip()), "")
+
+
+def _load(module_name: str) -> Callable[[list[str]], int]:
+    return importlib.import_module(module_name).main  # type: ignore[no-any-return]
+
+
+def _describe(module_name: str) -> str:
+    """Description for help output. main() docstring → module docstring → empty."""
+    mod = importlib.import_module(module_name)
+    desc = _first_doc_line(getattr(mod, "main", None))
+    return desc or _first_doc_line(mod)
+
+
+def _print_root_help() -> None:
+    print("usage: agentix <command> [args...]\n")
+    print("Agentix developer CLI\n")
+    print("commands:")
+    width = max(len(name) for name, _ in _COMMANDS) + 2
+    for name, mod in _COMMANDS:
+        print(f"  {name.ljust(width)}{_describe(mod)}")
+    print("\nRun `agentix <command> --help` for command-specific options.")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        _print_root_help()
+        return 0
+    cmd, *rest = argv
+    for name, mod in _COMMANDS:
+        if name == cmd:
+            return _load(mod)(rest)
+    print(f"unknown command: {cmd!r}\n", file=sys.stderr)
+    _print_root_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentix/cli/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m agentix.cli` entry point — defers to `agentix.cli.main`."""
+
+from __future__ import annotations
+
+import sys
+
+from agentix.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

agentix/cli/_resolve.py

@@ -0,0 +1,57 @@
+"""Read a project's pyproject.toml and derive build metadata.
+
+`agentix build` takes one project root — a directory containing
+`pyproject.toml`. Plugins (other `agentix-*` packages) are pulled in
+transitively via pip from the user's declared `[project].dependencies`;
+neither the CLI nor the user enumerates them on the command line.
+
+This module owns the small bit of metadata extraction the build needs:
+  * `read_pyproject(path)` — parse the project's pyproject.toml.
+  * `short_name(pyproject)` — display/tag short name derived from the
+    distribution name.
+  * `derive_tag(pyproject)` — `<short>:<version>` from name+version.
+
+There's no multi-spec resolver, no PyPI fallback, no path-vs-image
+disambiguation. The spec is always a local project root.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def read_pyproject(project_dir: Path) -> dict:
+    pp = project_dir / "pyproject.toml"
+    if not pp.is_file():
+        raise SystemExit(f"{project_dir}: missing pyproject.toml")
+    with pp.open("rb") as f:
+        return tomllib.load(f)
+
+
+def short_name(pyproject: dict) -> str:
+    """Derive a short display/tag name for the project.
+
+    The short name only affects the image tag and a few build
+    diagnostics — wire routing is by `fn.__module__`, which is
+    determined by the user's actual Python import path.
+    """
+    project = pyproject.get("project", {})
+    name = project.get("name", "")
+    if not isinstance(name, str) or not name:
+        raise SystemExit("pyproject.toml: [project].name is required")
+    return name.removeprefix("agentix-")
+
+
+def derive_tag(pyproject: dict) -> str:
+    """`<short>:<version>` from the pyproject."""
+    project = pyproject.get("project", {})
+    version = project.get("version")
+    if not isinstance(version, str):
+        raise SystemExit("pyproject.toml: [project].version is required")
+    return f"{short_name(pyproject)}:{version}"
+
+
+__all__ = ["REPO_ROOT", "derive_tag", "read_pyproject", "short_name"]

agentix/cli/build.py

@@ -0,0 +1,247 @@
+"""`agentix build` — package a Python project into a deploy-ready sandbox image.
+
+Usage:
+
+    agentix build                         # current directory's pyproject
+    agentix build path/to/project         # explicit project root
+    agentix build . -o my:0.1.0           # explicit image tag
+    agentix build . --dry-run             # stage Dockerfile to ./build/<tag>/, no docker invoke
+
+The single argument is a path to a directory containing `pyproject.toml`.
+That project's `[project].dependencies` are the bundle's plugin set —
+pip resolves them transitively, and the resulting wheels install into
+the framework's venv at `/nix/runtime/`. At runtime, calls execute the
+pickle-serialized callable payload. **Neither the CLI nor the user
+enumerates plugins on the command line.**
+
+Build shape:
+
+  * **One pip install for the whole bundle.** Your project + every
+    declared `agentix-*` dep + transitive deps install into a single
+    /nix/runtime/ venv. Inline imports across plugins work as regular
+    Python (`from agentix.bash import run` inside your worker resolves
+    because bash is in the same site-packages).
+
+  * **System binaries via Nix (optional).** If the project root carries
+    a `default.nix`, a Nix builder stage runs first; the derivation's
+    `bin/*` is symlinked into `/nix/runtime/bin/` so user code can
+    `subprocess.run("git", …)` without absolute paths. Plugins that
+    need their own system binaries are expected to declare them in the
+    user's project `default.nix` for now.
+
+The output image extends `agentix/runtime:<framework-version>` (override
+via `--runtime-image`). That base image must already exist locally —
+build it from `Agentix-Runtime-Basic/runtime/Dockerfile` or pull from
+a registry.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from agentix import __version__ as FRAMEWORK_VERSION
+from agentix.cli._resolve import REPO_ROOT, derive_tag, read_pyproject, short_name
+
+_SOURCE_SKIP = {
+    "__pycache__", ".venv", "build", "dist", ".git",
+    ".pytest_cache", ".ruff_cache", ".mypy_cache",
+}
+
+
+def _has_system_deps(src: Path) -> bool:
+    """True if the project ships a `default.nix` next to its pyproject."""
+    return (src / "default.nix").is_file()
+
+
+def _image_exists_locally(image: str) -> bool:
+    """`docker image inspect` returns 0 iff the image is locally present."""
+    proc = subprocess.run(
+        ["docker", "image", "inspect", image],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    return proc.returncode == 0
+
+
+def _ensure_runtime_image(runtime_image: str) -> None:
+    """Verify the runtime base image exists locally.
+
+    The Dockerfile ships with `agentix-runtime-basic`; users build it
+    from that repo or pull it from a registry. The bundle build
+    doesn't auto-build the base — making the user own that step keeps
+    `agentix build`'s scope narrow.
+    """
+    if _image_exists_locally(runtime_image):
+        return
+    raise SystemExit(
+        f"runtime image {runtime_image!r} not found locally. Build it from "
+        f"Agentix-Runtime-Basic (`runtime/Dockerfile`) or pull it from your "
+        f"registry, then re-run `agentix build`."
+    )
+
+
+def _stage(src: Path, build_dir: Path) -> None:
+    """Copy the project tree into `build_dir/project/`, skipping caches."""
+    dest = build_dir / "project"
+    dest.mkdir()
+    for item in src.iterdir():
+        if item.name in _SOURCE_SKIP or item.name.endswith(".egg-info"):
+            continue
+        d = dest / item.name
+        if item.is_dir():
+            shutil.copytree(item, d, ignore=shutil.ignore_patterns(*_SOURCE_SKIP))
+        else:
+            shutil.copy2(item, d)
+
+
+def _render_dockerfile(src: Path, runtime_image: str) -> str:
+    """Generate the bundle's Dockerfile.
+
+    Two stages, both optional in different ways:
+
+      Stage 1 (Nix builder, only if project has `default.nix`): build
+      the derivation, stash its closure + store-path so the next stage
+      can symlink binaries.
+
+      Stage 2 (final image): `FROM <runtime>`, copy the project source,
+      one `pip install /src/project` to merge everything into
+      `/nix/runtime/`. If a Nix derivation was built, symlink its
+      `bin/*` into `/nix/runtime/bin/`.
+    """
+    has_nix = _has_system_deps(src)
+    parts: list[str] = ["# Generated by `agentix build`. Do not hand-edit."]
+
+    if has_nix:
+        parts += [
+            "ARG NIX_IMAGE=nixos/nix:latest",
+            "",
+            "FROM ${NIX_IMAGE} AS sys-builder",
+            "RUN mkdir -p ~/.config/nix && \\",
+            "    echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf && \\",
+            "    nix-channel --update 2>/dev/null || true",
+            "RUN mkdir -p /export/nix/store /export/nix/.sys-paths",
+            "",
+            "WORKDIR /src/project",
+            "COPY project/ ./",
+            "RUN nix-build --no-out-link default.nix -o ./result && \\",
+            "    STORE_PATH=$(readlink -f ./result) && \\",
+            "    for p in $(nix-store -qR \"$STORE_PATH\"); do \\",
+            "        cp -a \"$p\" /export/nix/store/ || true; \\",
+            "    done && \\",
+            "    echo \"$STORE_PATH\" > /export/nix/.sys-paths/project",
+        ]
+
+    parts += ["", f"FROM {runtime_image}"]
+    if has_nix:
+        parts += [
+            "COPY --from=sys-builder /export/nix/store /nix/store",
+            "COPY --from=sys-builder /export/nix/.sys-paths /nix/.sys-paths",
+        ]
+
+    # Stage the source + install. Pip resolves the project's declared
+    # deps (including transitive agentix-* plugins) into /nix/runtime/.
+    parts += [
+        "COPY project/ /src/project/",
+        "RUN /nix/runtime/bin/pip install --no-cache-dir /src/project",
+    ]
+    if has_nix:
+        parts += [
+            "RUN SP=$(cat /nix/.sys-paths/project) && \\",
+            "    for f in $SP/bin/*; do \\",
+            "        ln -sf \"$f\" /nix/runtime/bin/$(basename \"$f\"); \\",
+            "    done",
+        ]
+    return "\n".join(parts) + "\n"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agentix build",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "path", nargs="?", default=".",
+        help="project root with pyproject.toml (default: current directory)",
+    )
+    parser.add_argument(
+        "-o", "--output", "--tag", dest="output", default=None,
+        help="output image tag. Defaults to <name>:<version> from pyproject.",
+    )
+    parser.add_argument(
+        "--runtime-image", default=f"agentix/runtime:{FRAMEWORK_VERSION}",
+        help="base runtime image. Must exist locally; build from "
+             "Agentix-Runtime-Basic/runtime/Dockerfile or pull from your "
+             f"registry. (default: agentix/runtime:{FRAMEWORK_VERSION})",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="stage Dockerfile to ./build/<tag>/; do not invoke docker",
+    )
+    args = parser.parse_args(argv)
+
+    src = Path(args.path).resolve()
+    if not src.is_dir():
+        raise SystemExit(f"{src}: not a directory")
+    pp = read_pyproject(src)
+
+    tag = args.output or derive_tag(pp)
+    if ":" not in tag:
+        raise SystemExit(f"image tag must include `:<version>` (got {tag!r})")
+
+    short = short_name(pp)
+
+    if args.dry_run:
+        out = REPO_ROOT / "build" / tag.rsplit("/", 1)[-1].split(":", 1)[0]
+        if out.exists():
+            shutil.rmtree(out)
+        out.mkdir(parents=True)
+        _stage(src, out)
+        (out / "Dockerfile").write_text(_render_dockerfile(src, args.runtime_image))
+        print(f"staged build context → {out}")
+        print(f"would build → {tag}")
+        print(f"  extends → {args.runtime_image}")
+        print(f"  project → {short}")
+        print(f"  nix derivation → {'yes' if _has_system_deps(src) else 'no'}")
+        return 0
+
+    _ensure_runtime_image(args.runtime_image)
+
+    with TemporaryDirectory(prefix="agentix-build-") as tmp:
+        build_dir = Path(tmp)
+        _stage(src, build_dir)
+        (build_dir / "Dockerfile").write_text(_render_dockerfile(src, args.runtime_image))
+        print(
+            f"building {tag} (project {short!r} extending {args.runtime_image})…",
+            file=sys.stderr,
+        )
+        proc = subprocess.run(
+            ["docker", "build", "-t", tag, str(build_dir)],
+            check=False,
+            stderr=subprocess.PIPE,
+        )
+        if proc.stderr:
+            sys.stderr.buffer.write(proc.stderr)
+        if proc.returncode != 0:
+            err = proc.stderr.decode(errors="replace") if proc.stderr else ""
+            if any(
+                token in err
+                for token in ("conflict", "no matching distribution", "incompatible", "ResolutionImpossible")
+            ):
+                print(
+                    "\nhint: pip couldn't resolve the unified dep set. Pin a "
+                    "compatible version pair across your `agentix-*` deps in "
+                    "pyproject.toml, or split the conflicting plugins into "
+                    "two bundles.",
+                    file=sys.stderr,
+                )
+        return proc.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentix/deployment/__init__.py

@@ -0,0 +1,16 @@
+"""Deployment Protocol + backend discovery.
+
+Core ships the `Deployment` Protocol, `Sandbox` dataclass, and backend
+registry. Backend wheels (`agentix-deployment-docker`, `-daytona`,
+`-e2b`, third-party) each install a sibling module under
+`agentix.deployment`; extending `__path__` lets those siblings co-exist
+with the framework files in this directory.
+"""
+
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+from agentix.deployment.base import Deployment
+
+__all__ = ["Deployment"]

agentix/deployment/_plugin.py

@@ -0,0 +1,202 @@
+"""Plugin registry for the `agentix.deployment` entry-point group.
+
+Lives under `agentix.deployment` because deployments are the only
+framework axis discovered via entry points. Remote callables do not need
+a framework registry; only sandbox lifecycle backends need a name-to-class
+registry.
+
+Two ways to find plugins:
+
+  * **Production:** `importlib.metadata.entry_points(group=...)` — what
+    `pip install some-plugin` populates. The dist's `pyproject.toml`
+    declares its entries; nothing in the framework changes when a new
+    plugin is installed.
+  * **Testing / dynamic:** the in-process `register(name, factory)`
+    method. Convenient for unit tests, fixtures, or programmatic
+    composition; not part of the documented user-facing surface.
+
+Lookup is lazy — entry points are walked on the first `get()` /
+`all()` call. Loaders that raise are caught and remembered per-entry
+(`errors()`), so one broken plugin doesn't poison the rest.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+logger = logging.getLogger("agentix.deployment.plugin")
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class PluginSource:
+    """Where a registered plugin came from — used in conflict reports
+    and CLI listings."""
+
+    dist_name: str | None
+    dist_version: str | None
+
+    def label(self) -> str:
+        if self.dist_name:
+            return f"{self.dist_name}@{self.dist_version or '?'}"
+        return "(in-process)"
+
+
+class PluginConflictError(RuntimeError):
+    """Two plugins claim the same name in the same group.
+
+    The framework refuses to silently last-wins because it would hide
+    bugs (e.g. a stale wheel from a previous install). Users see the
+    conflict on first registry access and uninstall the duplicate dist.
+    """
+
+
+class Registry(Generic[T]):
+    """One `agentix.<axis>` entry-point group + in-process `register()`.
+
+    `T` is whatever the entry-point load resolves to — typically a class
+    (`type[Deployment]`) or a callable factory. The registry doesn't
+    instantiate anything; callers decide what to do with the loaded
+    value. This keeps the contract narrow: T's shape is the axis's
+    Protocol; how it gets instantiated is the axis's concern.
+    """
+
+    def __init__(self, group: str) -> None:
+        self._group = group
+        self._extra: dict[str, tuple[Callable[[], T], PluginSource]] = {}
+        # Lazy: populated on first _load().
+        self._cache: dict[str, T] | None = None
+        self._sources: dict[str, PluginSource] = {}
+        self._errors: dict[str, Exception] = {}
+
+    @property
+    def group(self) -> str:
+        return self._group
+
+    def register(
+        self,
+        name: str,
+        factory: Callable[[], T],
+        *,
+        dist_name: str | None = None,
+        dist_version: str | None = None,
+    ) -> None:
+        """Register a plugin imperatively.
+
+        Intended for tests and programmatic composition; production
+        plugins use entry points. Calling `register()` invalidates the
+        cache so the next lookup re-runs the merge.
+        """
+        self._extra[name] = (factory, PluginSource(dist_name, dist_version))
+        self._cache = None  # invalidate
+
+    def _walk_entry_points(self) -> list[tuple[str, Callable[[], T], PluginSource]]:
+        eps = importlib.metadata.entry_points()
+        # Python 3.10+: SelectableGroups; earlier: dict (we target 3.11+ but
+        # mirror the standard library's defensive branch anyway).
+        selected = (
+            list(eps.select(group=self._group))
+            if hasattr(eps, "select")
+            else list(eps.get(self._group, []))  # type: ignore[attr-defined]
+        )
+        out: list[tuple[str, Callable[[], T], PluginSource]] = []
+        for ep in selected:
+            dist = ep.dist
+            src = PluginSource(
+                dist_name=getattr(dist, "name", None) if dist else None,
+                dist_version=getattr(dist, "version", None) if dist else None,
+            )
+            out.append((ep.name, ep.load, src))
+        return out
+
+    def _load(self) -> dict[str, T]:
+        if self._cache is not None:
+            return self._cache
+
+        items: dict[str, T] = {}
+        sources: dict[str, PluginSource] = {}
+        errors: dict[str, Exception] = {}
+
+        # Entry-point pass first. Two dists declaring the same name is
+        # ambiguous and must surface — they'd silently last-wins otherwise.
+        for name, loader, src in self._walk_entry_points():
+            if name in sources:
+                raise PluginConflictError(
+                    f"duplicate plugin {name!r} in group {self._group!r}: "
+                    f"{sources[name].label()} vs {src.label()}"
+                )
+            try:
+                items[name] = loader()
+                sources[name] = src
+            except Exception as exc:
+                logger.warning(
+                    "plugin %r in group %r failed to load: %s",
+                    name, self._group, exc,
+                )
+                errors[name] = exc
+
+        # In-process extras override entry points — this is deliberate
+        # for tests (`register("local", FakeDocker)` swaps in a stub).
+        # Production code paths don't call `register()`, so this is safe.
+        for name, (factory, src) in self._extra.items():
+            try:
+                items[name] = factory()
+                sources[name] = src
+                errors.pop(name, None)
+            except Exception as exc:
+                errors[name] = exc
+
+        self._cache = items
+        self._sources = sources
+        self._errors = errors
+        return items
+
+    def get(self, name: str) -> T:
+        """Return the plugin registered under `name`.
+
+        Raises `KeyError` if no plugin claims the name (with the list of
+        available names in the error message), or re-raises the original
+        exception if the named plugin failed to load.
+        """
+        items = self._load()
+        if name in items:
+            return items[name]
+        if name in self._errors:
+            raise self._errors[name]
+        raise KeyError(
+            f"no plugin {name!r} in group {self._group!r}; "
+            f"available: {sorted(items)}"
+        )
+
+    def all(self) -> dict[str, T]:
+        """Snapshot of all successfully-loaded plugins, name → value."""
+        return dict(self._load())
+
+    def sources(self) -> dict[str, PluginSource]:
+        """`name → PluginSource` for every successfully-loaded plugin."""
+        self._load()
+        return dict(self._sources)
+
+    def errors(self) -> dict[str, Exception]:
+        """`name → Exception` for plugins whose load failed (cached)."""
+        self._load()
+        return dict(self._errors)
+
+    def reset(self) -> None:
+        """Test-only: drop cache + in-process registrations.
+
+        Useful in pytest fixtures that need a known-empty registry
+        between tests.
+        """
+        self._cache = None
+        self._extra.clear()
+        self._sources.clear()
+        self._errors.clear()
+
+
+__all__ = ["PluginConflictError", "PluginSource", "Registry"]