agent-sandbox-server 0.3.1a1__py3-none-any.whl

agent_sandbox/server/__init__.py

@@ -0,0 +1,64 @@
+"""Container-side HTTP server — stdlib-only, zero external dependencies.
+
+Quick start (inside a sandbox template's ``commands.py``)::
+
+    from agent_sandbox.server import start
+    start(9000)
+
+Or for more control::
+
+    from agent_sandbox.server import SandboxServer, ServerPolicy, command
+
+    @command("greet")
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    server = SandboxServer(host="0.0.0.0", policy=ServerPolicy.only("transfer"))
+    server.serve(port=9000)
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .app import SandboxServer, start
+from .endpoints import CapabilityGroup
+from .policy import PolicyDenied, ServerPolicy
+from .registry import (
+    CommandArg,
+    CommandRegistry,
+    RegisteredCommand,
+    command,
+    default_registry,
+)
+from .router import RouteInfo, RouteTable, default_table
+from .routes_pty import (
+    PtySession,
+    PtySessionManager,
+    pty_session_manager,
+    start_pty_server,
+)
+from .types import ServerRequest, ServerResponse, SSEResponse
+
+__all__ = [
+    "__version__",
+    "SandboxServer",
+    "start",
+    "ServerPolicy",
+    "PolicyDenied",
+    "CommandArg",
+    "CommandRegistry",
+    "RegisteredCommand",
+    "command",
+    "default_registry",
+    "ServerRequest",
+    "ServerResponse",
+    "SSEResponse",
+    "RouteTable",
+    "RouteInfo",
+    "CapabilityGroup",
+    "default_table",
+    "PtySession",
+    "PtySessionManager",
+    "pty_session_manager",
+    "start_pty_server",
+]

agent_sandbox/server/__main__.py

@@ -0,0 +1,224 @@
+"""``agent-sandbox-server`` command line (also ``python -m agent_sandbox.server``).
+
+Sub-commands:
+
+* ``serve`` - run the HTTP (and PTY WebSocket) server.
+* ``healthcheck`` - ``GET /health`` against a running server; exit code 0/1 (Docker
+  ``HEALTHCHECK`` / platform ``ready_cmd``).
+* ``check-config`` - validate a policy, print the effective endpoint table and lint warnings.
+* ``version`` - print the package version.
+
+Stdlib only; ``healthcheck`` imports nothing heavy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import importlib.util
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+from . import contract
+from ._version import __version__
+
+__all__ = ["main"]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-sandbox-server", description=__doc__.split("\n")[0]
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    serve = sub.add_parser("serve", help="run the sandbox server")
+    serve.add_argument("--host", default="0.0.0.0")  # noqa: S104 (container-internal)
+    serve.add_argument("--port", type=int, default=contract.DEFAULT_HTTP_PORT)
+    serve.add_argument("--pty-port", type=int, default=None)
+    serve.add_argument(
+        "--commands",
+        action="append",
+        default=[],
+        metavar="FILE_OR_MODULE",
+        help="python file or module that registers commands/routes (repeatable)",
+    )
+    serve.add_argument("--policy", metavar="FILE", help="policy JSON file")
+    serve.add_argument("--preset", help="policy preset (default, transfer-only, ...)")
+    serve.add_argument("--base-dir", help="override ABX_SERVER_BASE_DIR")
+
+    health = sub.add_parser("healthcheck", help="GET /health, exit 0 when healthy")
+    health.add_argument("--host", default="127.0.0.1")
+    health.add_argument("--port", type=int, default=contract.DEFAULT_HTTP_PORT)
+    health.add_argument("--timeout", type=float, default=2.0)
+
+    check = sub.add_parser("check-config", help="validate and lint a policy")
+    check.add_argument("--policy", metavar="FILE")
+    check.add_argument("--preset")
+    check.add_argument("--json", action="store_true", help="machine-readable output")
+    check.add_argument("--strict", action="store_true", help="exit 2 when lint warnings exist")
+    check.add_argument("--explain", metavar="ENDPOINT", help="explain a decision for ENDPOINT")
+    check.add_argument("--path", help="path for --explain")
+    check.add_argument("--scopes", help="comma-separated scopes for --explain (default '*')")
+    check.add_argument("--op", choices=["read", "write", "delete", "exec"])
+
+    sub.add_parser("version", help="print the version")
+    return parser
+
+
+def _load_commands(spec: str) -> None:
+    """Import a file or module so its registrations run."""
+    if spec.endswith(".py") or os.path.sep in spec or os.path.isfile(spec):
+        path = os.path.realpath(spec)
+        module_name = f"_abx_user_commands_{hashlib.sha256(os.fsencode(path)).hexdigest()}"
+        if module_name in sys.modules:
+            return
+        module_spec = importlib.util.spec_from_file_location(module_name, path)
+        if module_spec is None or module_spec.loader is None:
+            raise SystemExit(f"cannot load commands file {spec!r}")
+        module = importlib.util.module_from_spec(module_spec)
+        previous_path = sys.path[:]
+        directory = os.path.dirname(path)
+        if directory not in sys.path:
+            sys.path.insert(0, directory)
+        # Decorators (including dataclasses with postponed annotations) resolve
+        # their defining module during execution, as with a normal import.
+        sys.modules[module_name] = module
+        try:
+            module_spec.loader.exec_module(module)
+        except BaseException:
+            sys.modules.pop(module_name, None)
+            sys.path[:] = previous_path
+            raise
+    else:
+        importlib.import_module(spec)
+
+
+def _resolve_policy(args: argparse.Namespace) -> Any:
+    from .policy import PolicyConfigError, ServerPolicy
+
+    try:
+        if args.policy:
+            policy = ServerPolicy.from_file(args.policy)
+            if args.preset:
+                policy = policy.with_options(preset=args.preset)
+            return policy
+        if args.preset:
+            return ServerPolicy.preset(args.preset)
+        return ServerPolicy.from_environment()
+    except PolicyConfigError as exc:
+        print(f"policy error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    from .app import SandboxServer
+
+    if args.base_dir:
+        os.environ["ABX_SERVER_BASE_DIR"] = args.base_dir
+    for spec in args.commands:
+        _load_commands(spec)
+    policy = _resolve_policy(args)
+    try:
+        server = SandboxServer(host=args.host, pty_port=args.pty_port, policy=policy)
+    except ValueError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return 1
+    server.serve(args.port)
+    return 0
+
+
+def _cmd_healthcheck(args: argparse.Namespace) -> int:
+    url = f"http://{args.host}:{args.port}/health"
+    try:
+        with urllib.request.urlopen(url, timeout=args.timeout) as resp:  # noqa: S310
+            return 0 if resp.status == 200 else 1
+    except (urllib.error.URLError, OSError, ValueError):
+        return 1
+
+
+def _cmd_check_config(args: argparse.Namespace) -> int:
+    from .policy import PolicyConfigError, ServerPolicy
+
+    policy = _resolve_policy(args) or ServerPolicy.from_dict({})
+    try:
+        engine = policy.bind()
+    except PolicyConfigError as exc:
+        print(f"policy error: {exc}", file=sys.stderr)
+        return 1
+    warnings = engine.lint()
+    if args.policy:
+        warnings.extend(_file_permission_warnings(args.policy))
+    if args.explain:
+        scopes = args.scopes.split(",") if args.scopes else None
+        decision = engine.explain(args.explain, scopes=scopes, path=args.path, op=args.op)
+        print(json.dumps(decision, indent=2))
+        return 0 if decision["allowed"] else 3
+    rows = []
+    for name in sorted(engine._rules):
+        rule = engine.rule_for(name)
+        route = engine._routes[name]
+        rows.append(
+            {
+                "endpoint": name,
+                "group": route.group.value,
+                "enabled": rule.enabled,
+                "rule": rule.disabled_by or None,
+                "scopes": list(rule.scopes),
+                "limits": dict(rule.limits),
+                "paths": {
+                    "allow": list(rule.allow),
+                    "deny": list(rule.deny),
+                    "read_only": rule.read_only,
+                },
+            }
+        )
+    if args.json:
+        print(
+            json.dumps(
+                {"revision": policy.revision, "endpoints": rows, "warnings": warnings}, indent=2
+            )
+        )
+    else:
+        print(f"policy {policy!r}")
+        for row in rows:
+            flag = "on " if row["enabled"] else "off"
+            print(f"  [{flag}] {row['endpoint']:<24} scopes={','.join(row['scopes']) or '-'}")
+        for warning in warnings:
+            print(f"warning: {warning}")
+    return 2 if warnings and args.strict else 0
+
+
+def _file_permission_warnings(path: str) -> list[str]:
+    out: list[str] = []
+    if os.access(path, os.W_OK):
+        out.append(f"L5: policy file {path} is writable by the current user")
+    directory = os.path.dirname(os.path.abspath(path))
+    if os.access(directory, os.W_OK):
+        out.append(f"L5: policy directory {directory} is writable by the current user")
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point; returns the process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "serve"
+    if command == "serve" and args.command is None:
+        args = parser.parse_args(["serve", *(argv or [])])
+    if command == "version":
+        print(__version__)
+        return 0
+    if command == "healthcheck":
+        return _cmd_healthcheck(args)
+    if command == "check-config":
+        return _cmd_check_config(args)
+    return _cmd_serve(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

agent_sandbox/server/_coerce.py

@@ -0,0 +1,169 @@
+"""Shared scalar and string-array type coercion for command arguments.
+
+Both the **server** layer (``server/routes.py``) and the client SDK's
+**declarative** layer (``declarative/decorator.py``) need identical
+coerce-and-validate logic.  The server-sdk and client-sdk are separate
+distributions, so each ships this module (``agent_sandbox.utils.coerce`` in the
+client); the two files must stay byte-identical, which the client test-suite
+enforces.
+
+The functions accept any arg object exposing ``.name``, ``.type``,
+``.required``, and ``.default`` attributes — covering both
+:class:`~agent_sandbox.server.registry.CommandArg` (stdlib dataclass) and
+:class:`~agent_sandbox.models.template.CustomCommandArg` (Pydantic model).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = [
+    "parse_scalar",
+    "coerce_kwargs",
+]
+
+# ---------------------------------------------------------------------------
+# Boolean whitelist
+# ---------------------------------------------------------------------------
+
+_BOOL_TRUE: frozenset[str] = frozenset({"true", "yes", "1"})
+_BOOL_FALSE: frozenset[str] = frozenset({"false", "no", "0"})
+
+# ---------------------------------------------------------------------------
+# Scalar parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_scalar(value: Any, type_str: str) -> Any:
+    """Parse / coerce *value* according to its declared *type_str*.
+
+    Supported *type_str* values: ``"string"``, ``"integer"``, ``"float"``,
+    ``"boolean"``, and ``"string_array"`` (JSON arrays of strings only).
+
+    Bool parsing uses a whitelist (``true/false/yes/no/1/0``) to avoid the
+    ``bool("False") == True`` pitfall.
+
+    Args:
+        value: The raw value to coerce.
+        type_str: One of the supported scalar type strings.
+
+    Returns:
+        The coerced value.
+
+    Raises:
+        ValueError: If *value* cannot be converted or *type_str* is
+            unrecognised.
+    """
+    if type_str == "string":
+        return str(value)
+
+    if type_str == "integer":
+        if isinstance(value, bool):
+            raise ValueError("JSON boolean is not an integer argument")
+        if isinstance(value, int) and not isinstance(value, bool):
+            return value
+        return int(value)
+
+    if type_str == "float":
+        if isinstance(value, float):
+            return value
+        return float(value)
+
+    if type_str == "boolean":
+        if isinstance(value, bool):
+            return value
+        s = str(value).lower()
+        if s in _BOOL_TRUE:
+            return True
+        if s in _BOOL_FALSE:
+            return False
+        raise ValueError(
+            f"Cannot parse {value!r} as boolean; accepted values: true/false/yes/no/1/0"
+        )
+
+    if type_str == "string_array":
+        if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+            raise ValueError("Expected a JSON array containing only strings")
+        return list(value)
+
+    raise ValueError(f"Unknown type: {type_str!r}")
+
+
+# ---------------------------------------------------------------------------
+# Arg-like protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class ArgLike(Protocol):
+    """Minimal interface shared by ``CommandArg`` and ``CustomCommandArg``."""
+
+    name: str
+    type: str
+    required: bool
+    default: str | None
+
+
+# ---------------------------------------------------------------------------
+# Kwargs coercion / validation
+# ---------------------------------------------------------------------------
+
+
+def coerce_kwargs(
+    args: list[Any],
+    raw: dict[str, Any],
+) -> dict[str, Any]:
+    """Coerce and validate *raw* kwargs against *args* definitions.
+
+    Args:
+        args: Ordered list of arg descriptors (anything with ``.name``,
+            ``.type``, ``.required``, ``.default``).
+        raw: Raw keyword arguments from the caller / JSON body.
+
+    Returns:
+        A new dict with values converted to the declared types.
+
+    Raises:
+        ValueError: If a required argument is missing or an undeclared
+            argument is provided.
+        TypeError: If a value cannot be converted to the declared type.
+    """
+    declared_names: set[str] = {arg.name for arg in args}
+
+    # --- Reject undeclared arguments early (fail-fast) ---
+    undeclared = sorted(k for k in raw if k not in declared_names)
+    if undeclared:
+        raise ValueError(
+            f"Unexpected argument(s): {undeclared}; declared: {sorted(declared_names) or '(none)'}"
+        )
+
+    # --- Coerce declared arguments ---
+    coerced: dict[str, Any] = {}
+    for arg in args:
+        if arg.name in raw:
+            try:
+                coerced[arg.name] = parse_scalar(raw[arg.name], arg.type)
+            except (ValueError, TypeError) as exc:
+                raise TypeError(
+                    f"Cannot convert argument {arg.name!r} to {arg.type}: {exc}"
+                ) from exc
+        elif arg.required:
+            raise ValueError(f"Required argument {arg.name!r} missing")
+        elif arg.default is not None:
+            if arg.type == "string_array":
+                try:
+                    coerced[arg.name] = parse_scalar(json.loads(arg.default), arg.type)
+                except (ValueError, TypeError) as exc:
+                    raise TypeError(
+                        f"Invalid string_array default for argument {arg.name!r}"
+                    ) from exc
+                continue
+            # Best-effort coercion of the default; fall back to the raw
+            # string if conversion fails (e.g. a placeholder like "N/A").
+            try:
+                coerced[arg.name] = parse_scalar(arg.default, arg.type)
+            except (ValueError, TypeError):
+                coerced[arg.name] = arg.default
+
+    return coerced

agent_sandbox/server/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.1a1"

agent_sandbox/server/agents/__init__.py

@@ -0,0 +1,66 @@
+"""Hosted coding-agent runtime for the sandbox HTTP server (opt-in ``agents`` group).
+
+Public extension API::
+
+    from agent_sandbox.server.agents import AgentAdapter, register_adapter
+
+See ``docs/en/design/agents-api.md``.
+"""
+
+from __future__ import annotations
+
+from . import events
+from .adapters import (
+    AdapterCapabilities,
+    AdapterRegistry,
+    AgentAdapter,
+    EventParser,
+    Invocation,
+    InvocationFile,
+    TurnContext,
+    default_adapters,
+    register_adapter,
+)
+from .config import (
+    AgentSpec,
+    GitSpec,
+    LimitsSpec,
+    McpServerSpec,
+    ProviderSpec,
+    WorkspaceSpec,
+)
+from .errors import AgentConfigError, AgentNotFoundError, AgentRuntimeError
+from .events import ParsedEvent
+from .redact import Redactor
+from .runtime import AgentRuntime, Item, RuntimeEvent, Session, Turn
+from .store import AgentStore
+
+__all__ = [
+    "AdapterCapabilities",
+    "AdapterRegistry",
+    "AgentAdapter",
+    "AgentConfigError",
+    "AgentNotFoundError",
+    "AgentRuntime",
+    "AgentRuntimeError",
+    "AgentSpec",
+    "AgentStore",
+    "EventParser",
+    "GitSpec",
+    "Invocation",
+    "InvocationFile",
+    "Item",
+    "LimitsSpec",
+    "McpServerSpec",
+    "ParsedEvent",
+    "ProviderSpec",
+    "Redactor",
+    "RuntimeEvent",
+    "Session",
+    "Turn",
+    "TurnContext",
+    "WorkspaceSpec",
+    "default_adapters",
+    "events",
+    "register_adapter",
+]

agent_sandbox/server/agents/adapters/__init__.py

@@ -0,0 +1,140 @@
+"""Adapter registry: built-ins, entry points and ``ABX_AGENTS_ADAPTER_MODULES``."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import threading
+
+from .base import (
+    AdapterCapabilities,
+    AgentAdapter,
+    EventParser,
+    Invocation,
+    InvocationFile,
+    TurnContext,
+)
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+from .command import CommandAdapter
+from .cursor import CursorAdapter
+from .qwen_code import QwenCodeAdapter
+
+__all__ = [
+    "AdapterCapabilities",
+    "AdapterRegistry",
+    "AgentAdapter",
+    "EventParser",
+    "Invocation",
+    "InvocationFile",
+    "TurnContext",
+    "default_adapters",
+    "register_adapter",
+    "ENTRY_POINT_GROUP",
+    "MODULES_ENV_VAR",
+]
+
+ENTRY_POINT_GROUP = "agent_sandbox.agent_adapters"
+MODULES_ENV_VAR = "ABX_AGENTS_ADAPTER_MODULES"
+
+_log = logging.getLogger(__name__)
+
+
+class AdapterRegistry:
+    """Name/alias → adapter class registry."""
+
+    def __init__(self, *, builtins: bool = True) -> None:
+        self._classes: dict[str, type[AgentAdapter]] = {}
+        self._aliases: dict[str, str] = {}
+        self._lock = threading.Lock()
+        if builtins:
+            for cls in (
+                CodexAdapter,
+                ClaudeCodeAdapter,
+                CursorAdapter,
+                QwenCodeAdapter,
+                CommandAdapter,
+            ):
+                self.register(cls)
+
+    def register(self, cls: type[AgentAdapter], *, override: bool = False) -> type[AgentAdapter]:
+        """Register *cls*; a name/alias clash is an error unless ``override=True``."""
+        name = getattr(cls, "name", None)
+        if not name or not isinstance(name, str):
+            raise ValueError(f"{cls!r} must define a non-empty class attribute 'name'")
+        with self._lock:
+            keys = (name, *cls.aliases)
+            if not override:
+                for key in keys:
+                    owner = self._aliases.get(key) or (key if key in self._classes else None)
+                    if owner is not None and owner != name:
+                        raise ValueError(
+                            f"adapter name/alias {key!r} is already registered by {owner!r}"
+                        )
+                if name in self._classes:
+                    raise ValueError(f"adapter {name!r} is already registered (use override=True)")
+            self._classes[name] = cls
+            for alias in cls.aliases:
+                self._aliases[alias] = name
+        return cls
+
+    def resolve_name(self, name: str) -> str | None:
+        """Canonical adapter name for *name* or an alias (``None`` if unknown)."""
+        key = name.strip().lower()
+        if key in self._classes:
+            return key
+        return self._aliases.get(key)
+
+    def get(self, name: str) -> AgentAdapter | None:
+        """A fresh adapter instance for *name* (or alias)."""
+        canonical = self.resolve_name(name)
+        return self._classes[canonical]() if canonical else None
+
+    def names(self) -> list[str]:
+        """Canonical adapter names."""
+        return sorted(self._classes)
+
+    def load_plugins(self) -> list[str]:
+        """Load entry-point and env-var adapters; returns the names loaded."""
+        loaded: list[str] = []
+        try:
+            from importlib.metadata import entry_points
+
+            for ep in entry_points(group=ENTRY_POINT_GROUP):
+                try:
+                    cls = ep.load()
+                    self.register(cls)
+                    loaded.append(cls.name)
+                except Exception as exc:  # plugin errors must not break the server
+                    _log.warning("failed to load agent adapter entry point %s: %s", ep.name, exc)
+        except Exception as exc:
+            _log.debug("entry point discovery failed: %s", exc)
+        for module in filter(
+            None, (m.strip() for m in os.environ.get(MODULES_ENV_VAR, "").split(","))
+        ):
+            try:
+                importlib.import_module(module)
+            except Exception as exc:
+                _log.warning("failed to import agent adapter module %s: %s", module, exc)
+        return loaded
+
+
+_default = AdapterRegistry()
+_plugins_loaded = False
+_plugins_lock = threading.Lock()
+
+
+def default_adapters() -> AdapterRegistry:
+    """The process-wide registry (plugins are discovered on first use)."""
+    global _plugins_loaded
+    with _plugins_lock:
+        if not _plugins_loaded:
+            _plugins_loaded = True
+            _default.load_plugins()
+    return _default
+
+
+def register_adapter(cls: type[AgentAdapter], *, override: bool = False) -> type[AgentAdapter]:
+    """Register *cls* in the default registry (usable as a class decorator)."""
+    return _default.register(cls, override=override)