agentnode-sdk 0.11.4__tar.gz → 0.12.0__tar.gz

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.0}/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.12.0 — Sandboxed community agents (flag-gated)
+
+### Added
+
+- **Agent sandbox (default OFF):** with `AGENTNODE_AGENT_SANDBOX=1` (or config
+  `agent_sandbox.enabled: true`), `verified`/`unverified` community agents run
+  **sandbox-or-fail-closed** in the pinned container image — never on the host,
+  with **no host fallback** anywhere on the path. Tool calls cross an
+  allowlisted RPC back to the host's gated runner (the host owns allowlist and
+  limits); `trusted`/`curated` agents are unchanged. With the flag OFF
+  (default), community agents remain refused exactly as in 0.11.4.
+- **Host-side LLM broker:** sandboxed agents request completions via RPC; the
+  provider call runs host-side and **provider API keys never enter the
+  container** (the container env is only `PYTHONPATH=/pack`).
+- **`llm_access` manifest block (default-deny):** a sandboxed agent gets NO
+  host LLM unless its manifest declares `llm_access.enabled: true` — analogous
+  to `tool_access`. Caps: `max_calls`, `max_input_chars`, `max_output_chars`;
+  optional `allowed_models` checks the HOST-chosen model (the agent never picks
+  a model; absent = unrestricted, `[]` = refuse-all, manifest+host = both must
+  allow). The host ceiling (`agent_sandbox.llm` in `~/.agentnode/config.json`)
+  always wins — it can lower caps, restrict models, or disable access entirely.
+  Refused/failed LLM calls return **graceful per-call errors** the agent can
+  catch; they never crash the run and never fall back to the host.
+- **Audit:** every sandboxed run writes ONE aggregated, sanitized record to
+  `~/.agentnode/audit.jsonl` (`event: agent_run`, `source: agent_sandbox`) —
+  counters, caps, and fixed reason codes only; **never prompts, keys, raw
+  provider errors, or agent-authored error text**. Fail-closed refusals
+  (missing volume/runtime, session-start failure) are audited too.
+- Agent manifest template (`agentnode init`) now documents the opt-in
+  `llm_access` block with the caps and `allowed_models`.
+
+### Changed
+
+- `agentnode init` agent template includes the `llm_access` example (newly
+  scaffolded packages only; existing manifests are unaffected — an absent
+  `llm_access` simply means deny).
+
+### Hardened
+
+- The sandbox path is fail-closed end to end: missing/stale volume, missing
+  container runtime or pinned image, sandbox-start failure, or a host-loop
+  error all return a clean `sandbox_unavailable`/error result — community
+  agent code never executes on the host.
+- LLM broker errors are generic and leak-free (no key, no provider internals,
+  no prompt echo). A model-allowlist refusal never calls the provider (no
+  charge), and the host-side model name is never sent into the sandbox.
+
+### BREAKING / Upgrade Notes
+
+- **None.** With the flag OFF (default), behavior is identical to 0.11.4.
+  There are no flag-ON users yet (the flag ships first in this release).
+- Enabling the agent sandbox requires a container runtime plus the pinned
+  public sandbox image — `agentnode sandbox pull` to fetch it,
+  `agentnode sandbox doctor` for diagnosis.
+- Operational note for managed hosts (e.g. Coolify): automatic image pruning
+  can remove the pinned sandbox image, degrading community execution to
+  fail-closed until it is re-pulled. Keep the image pinned (e.g. a minimal
+  keep-alive holder container referencing the digest) or re-pull on a
+  schedule.
+
 ## 0.11.4 — Publish confirm gate
 
 ### Added

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.11.4
+Version: 0.12.0
 Summary: Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.
 Project-URL: Homepage, https://agentnode.net
 Project-URL: Repository, https://github.com/agentnode-ai/agentnode

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.0}/agentnode_sdk/__init__.py

@@ -38,7 +38,7 @@ from agentnode_sdk.runtime import AgentNodeRuntime
 Client = AgentNodeClient
 ToolError = AgentNodeToolError
 
-__version__ = "0.11.4"
+__version__ = "0.12.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.0}/agentnode_sdk/cli/templates.py

@@ -655,6 +655,21 @@ agent:
   tier: "llm_only"
   llm:
     required: true
+  llm_access:
+    # Host-brokered LLM access for SANDBOXED community runs (opt-in).
+    # When your agent runs sandboxed on someone else's machine, it can only
+    # reach their LLM credentials through the host broker, and only if you
+    # set enabled: true here. Default false = no access (calls fail gracefully).
+    # The host's own ceiling (agent_sandbox.llm in the host config) ALWAYS
+    # wins: it can lower these caps or disable access entirely.
+    enabled: false
+    max_calls: 20
+    max_input_chars: 24000
+    max_output_chars: 24000
+    # Optionally restrict which host-chosen models may serve this agent
+    # (the agent cannot pick a model; the host does). Omit = any host model.
+    # An explicit empty list means no model is acceptable.
+    # allowed_models: ["gpt-4o-mini", "claude-3-5-haiku-latest"]
   system_prompt: |
     You are a helpful agent that accomplishes goals step by step.
     Think carefully, use available tools, and return a clear result.

agentnode_sdk-0.12.0/agentnode_sdk/runtimes/agent_llm_broker.py

@@ -0,0 +1,83 @@
+"""Host-side LLM broker for sandboxed agents (B2b-1).
+
+A sandboxed community agent requests an LLM completion via the ``call_llm`` RPC;
+the HOST runs the actual provider call here. The provider API key stays host-side
+and NEVER enters the sandbox — the broker receives only ``messages`` and returns
+only a structured completion. A PURE RELAY: it never interprets messages as host
+commands. Errors are GENERIC — the raw provider exception (which can contain the
+key, request URLs, or internal details) is never surfaced to the agent.
+
+Credential policy (caps, default-deny, audit) lives in ``agent_llm_policy`` —
+this module is only the secure provider plumbing. C2 adds one policy hook here:
+an optional ``allowed_models`` check, because the effective model (incl. the
+default fallback) is only known at this point.
+"""
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("agentnode.agent_sandbox")
+
+# Used only when the host LLM binding does not specify a model.
+_DEFAULT_MODELS = {
+    "openai": "gpt-4o-mini",
+    "anthropic": "claude-3-5-haiku-latest",
+}
+
+
+class LlmBrokerError(RuntimeError):
+    """Generic, leak-free LLM broker failure (no key, no provider internals)."""
+
+
+class LlmModelNotAllowedError(LlmBrokerError):
+    """C2: the host-chosen model is outside the effective ``allowed_models`` set.
+
+    The MESSAGE stays generic (it crosses into the sandbox); the host-side model
+    name travels only on the ``model`` attribute, for audit.
+    """
+
+    def __init__(self, model: str = ""):
+        super().__init__("the host-configured LLM model is not allowed for this agent")
+        self.model = model
+
+
+def host_llm_broker(messages: list, *, allowed_models=None) -> dict:
+    """Run one LLM completion HOST-side and return ``{"role","content"}``.
+
+    ``allowed_models`` (optional, C2 defense-in-depth): a set of model ids the
+    host-chosen model must be in — the agent never picks a model, this only
+    checks the one the host resolved (incl. the default fallback). Not allowed →
+    :class:`LlmModelNotAllowedError` WITHOUT calling the provider.
+
+    Raises :class:`LlmBrokerError` (generic) on any failure — no provider /
+    missing SDK / provider exception — never leaking the key or the raw provider
+    exception text.
+    """
+    from agentnode_sdk.runtimes.agent_runner import _auto_detect_llm
+
+    binding = _auto_detect_llm()
+    if not binding:
+        raise LlmBrokerError("no LLM provider configured on the host")
+
+    client = binding.get("client")
+    provider = binding.get("provider")
+    model = binding.get("model") or _DEFAULT_MODELS.get(provider or "", "")
+    if client is None or provider not in _DEFAULT_MODELS:
+        raise LlmBrokerError("unsupported or unavailable LLM provider")
+
+    if allowed_models is not None and model not in allowed_models:
+        logger.warning("LLM broker refused a model outside allowed_models")
+        raise LlmModelNotAllowedError(model)
+
+    try:
+        if provider == "openai":
+            resp = client.chat.completions.create(model=model, messages=list(messages or []))
+            content = resp.choices[0].message.content
+        else:  # anthropic
+            resp = client.messages.create(model=model, max_tokens=1024, messages=list(messages or []))
+            content = resp.content[0].text
+    except Exception as exc:  # never surface the raw provider error (may carry the key)
+        logger.warning("LLM broker provider call failed: %s", type(exc).__name__)
+        raise LlmBrokerError("LLM provider call failed")
+
+    return {"role": "assistant", "content": content or ""}

agentnode_sdk-0.12.0/agentnode_sdk/runtimes/agent_llm_policy.py

@@ -0,0 +1,184 @@
+"""C1 — host-credential LLM broker policy for sandboxed community agents.
+
+This protects the HOST USER's LLM credentials/wallet from UNTRUSTED
+(verified/unverified) sandboxed community code that borrows the host key via the
+broker. It is NOT a limit on agents in general: trusted/curated/self-run agents
+(own key, host path) are unaffected — they keep "run until done".
+
+DEFAULT-DENY: like ``tool_access``, an agent reaches the host LLM only if it
+explicitly declares ``llm_access.enabled: true`` in its manifest. The host-config
+ceiling (``agent_sandbox.llm`` in ~/.agentnode/config.json) ALWAYS wins — it can
+lower the caps or force-disable, and a higher manifest value is clamped to it.
+
+Refusals/errors come back as a STRUCTURED ``{"ok": False, "error": ...}`` so the
+RPC host can return them as graceful per-call errors the agent can catch — never
+a whole-run crash, never a host fallback. Errors are sanitized: no key, no prompt,
+no raw provider internals.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentnode_sdk.runtimes.agent_llm_broker import LlmBrokerError, LlmModelNotAllowedError
+
+# Conservative built-in ceilings: the fallback when the host config does not set a
+# field, and the default the manifest request is clamped against.
+_DEFAULT_MAX_CALLS = 20
+_DEFAULT_MAX_INPUT_CHARS = 24_000
+_DEFAULT_MAX_OUTPUT_CHARS = 24_000
+
+
+@dataclass(frozen=True)
+class LlmAccessPolicy:
+    """Resolved per-run LLM access policy for one sandboxed community agent.
+
+    ``allowed_models`` (C2): ``None`` = unrestricted (the host picks the model
+    anyway); a frozenset = only those host-chosen models may serve the agent
+    (an empty set refuses all — same convention as tool_access.allowed_packages).
+    """
+
+    enabled: bool = False
+    max_calls: int = 0
+    max_input_chars: int = 0
+    max_output_chars: int = 0
+    allowed_models: frozenset | None = None
+
+
+def _ceiling(host_llm: dict, key: str, default: int) -> int:
+    """The host-config ceiling for ``key`` (a positive int), else the built-in."""
+    try:
+        v = int(host_llm[key])
+    except (KeyError, TypeError, ValueError):
+        return int(default)
+    return v if v > 0 else int(default)
+
+
+def _request(manifest: dict, key: str, ceiling: int) -> int:
+    """The manifest's requested value for ``key`` (positive int), else the ceiling."""
+    try:
+        v = int(manifest[key])
+    except (KeyError, TypeError, ValueError):
+        return ceiling
+    return v if v > 0 else ceiling
+
+
+def _models_set(section: dict) -> frozenset | None:
+    """``allowed_models`` as a frozenset, or ``None`` when absent / not a list.
+
+    Convention (mirrors ``tool_access.allowed_packages``): absent → ``None`` =
+    unrestricted; an explicit ``[]`` → empty set = no model is acceptable.
+    """
+    raw = section.get("allowed_models")
+    if not isinstance(raw, list):
+        return None
+    return frozenset(s for s in (str(x).strip() for x in raw) if s)
+
+
+def resolve_llm_policy(agent_config: dict | None, host_config: dict | None = None) -> LlmAccessPolicy:
+    """Resolve the effective policy = min(manifest request, host ceiling).
+
+    Default-deny: a missing ``llm_access`` or ``enabled != true`` → disabled. The
+    host config can also force-disable (``agent_sandbox.llm.enabled: false``).
+    ``allowed_models``: both sides set → intersection (both must allow); one side
+    set → that side; neither → unrestricted.
+    """
+    manifest = ((agent_config or {}).get("llm_access")) or {}
+    host_llm = ((((host_config or {}).get("agent_sandbox")) or {}).get("llm")) or {}
+
+    manifest_enabled = manifest.get("enabled") is True
+    host_enabled = host_llm.get("enabled", True)  # host omits → defer to manifest
+    if not (manifest_enabled and host_enabled is not False):
+        return LlmAccessPolicy(enabled=False)
+
+    mc = _ceiling(host_llm, "max_calls", _DEFAULT_MAX_CALLS)
+    ic = _ceiling(host_llm, "max_input_chars", _DEFAULT_MAX_INPUT_CHARS)
+    oc = _ceiling(host_llm, "max_output_chars", _DEFAULT_MAX_OUTPUT_CHARS)
+    m, h = _models_set(manifest), _models_set(host_llm)
+    models = (m & h) if (m is not None and h is not None) else (m if m is not None else h)
+    return LlmAccessPolicy(
+        enabled=True,
+        max_calls=min(_request(manifest, "max_calls", mc), mc),
+        max_input_chars=min(_request(manifest, "max_input_chars", ic), ic),
+        max_output_chars=min(_request(manifest, "max_output_chars", oc), oc),
+        allowed_models=models,
+    )
+
+
+def _input_chars(messages) -> int:
+    return sum(len(str((m or {}).get("content", "") or "")) for m in (messages or []))
+
+
+def make_policy_broker(policy: LlmAccessPolicy, base_broker):
+    """Wrap ``base_broker`` (the host LLM broker) with policy enforcement.
+
+    Returns a callable ``(messages) -> {"ok": bool, "completion"?|"error"?}``.
+    Per-run state (the call counter) lives in this closure, so one run gets one
+    fresh budget. Never raises — all failures are structured + sanitized so the
+    RPC host turns them into graceful per-call errors (no host fallback).
+
+    C2: the callable exposes ``broker.usage`` (live per-run counters for the
+    aggregated audit record — counts, reason codes, and at most the HOST-side
+    model name; never message content) and ``broker.policy`` (the resolved
+    policy). ``allowed_models`` is forwarded to ``base_broker`` ONLY when the
+    policy sets it, so plain single-arg brokers/fakes keep working unchanged.
+    """
+    state = {
+        "requests": 0,
+        "calls": 0,
+        "ok": 0,
+        "refused_disabled": 0,
+        "refused_limit": 0,
+        "refused_input": 0,
+        "refused_output": 0,
+        "refused_model": 0,
+        "provider_errors": 0,
+        "model": None,
+    }
+
+    def broker(messages):
+        state["requests"] += 1
+        if not policy.enabled:
+            state["refused_disabled"] += 1
+            return {"ok": False, "error":
+                    "LLM access not granted: this agent did not declare llm_access.enabled"}
+
+        state["calls"] += 1
+        if state["calls"] > policy.max_calls:
+            state["refused_limit"] += 1
+            return {"ok": False, "error": "LLM call limit reached for this run"}
+
+        if _input_chars(messages) > policy.max_input_chars:
+            state["refused_input"] += 1
+            return {"ok": False, "error": "LLM request exceeds the allowed input size"}
+
+        try:
+            if policy.allowed_models is not None:
+                completion = base_broker(messages, allowed_models=policy.allowed_models)
+            else:
+                completion = base_broker(messages)
+        except LlmModelNotAllowedError as exc:
+            # Generic message to the agent; the host-side model name goes only
+            # into the usage counters (for audit), never into the sandbox.
+            state["refused_model"] += 1
+            state["model"] = getattr(exc, "model", "") or None
+            return {"ok": False, "error": str(exc)}
+        except LlmBrokerError as exc:
+            # LlmBrokerError is our own already-sanitized type (no key/internals).
+            state["provider_errors"] += 1
+            return {"ok": False, "error": str(exc)}
+        except Exception:
+            # Never surface a raw provider/host exception (may carry secrets).
+            state["provider_errors"] += 1
+            return {"ok": False, "error": "LLM call failed"}
+
+        content = str(completion.get("content", "") or "") if isinstance(completion, dict) else ""
+        if len(content) > policy.max_output_chars:
+            state["refused_output"] += 1
+            return {"ok": False, "error": "LLM response exceeds the allowed output size"}
+
+        state["ok"] += 1
+        return {"ok": True, "completion": completion}
+
+    broker.usage = state
+    broker.policy = policy
+    return broker

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.0}/agentnode_sdk/runtimes/agent_runner.py

@@ -1252,6 +1252,13 @@ def run_agent(
     # or community code runs unsandboxed (reintroducing the RCE class the sandbox
     # bow closed). Locked by test_agent_runner's execution-vector regression test.
     trust_level = entry.get("trust_level", "unverified")
+    # B2a: with the agent-sandbox flag ON, community (verified/unverified) agents
+    # run sandboxed-or-fail-closed (never host) instead of being refused. Flag OFF
+    # (default) ⇒ this branch is skipped ⇒ behaviour is unchanged (the gate below
+    # refuses them). trusted/curated always fall through to the host path.
+    from agentnode_sdk.runtimes.agent_sandbox import _agent_sandbox_enabled, run_agent_sandboxed
+    if _agent_sandbox_enabled() and trust_level in ("verified", "unverified"):
+        return run_agent_sandboxed(slug, entry, agent_config, goal=goal, run_id=run_id, **kwargs)
     if not _trust_meets_minimum(trust_level, "trusted"):
         _audit_agent_run(
             slug, success=False,

agentnode_sdk-0.12.0/agentnode_sdk/runtimes/agent_sandbox.py

@@ -0,0 +1,218 @@
+"""B2a: route community (verified/unverified) agents through a sandboxed session,
+behind a default-OFF feature flag.
+
+Policy (only when the flag is ON):
+  verified / unverified  -> sandbox-or-fail-closed (this module); NEVER host.
+  trusted / curated      -> host (handled in run_agent, unchanged).
+  unknown / missing       -> refused (run_agent's existing gate).
+
+This is the FIRST behaviour change of the agent-sandbox bow. With the flag OFF
+(default) nothing here runs and run_agent behaves exactly as before. No host
+fallback: if no backend/volume is available, fail-closed. Tool-calls go host-side
+through the real ``runner.run_tool`` (via AgentRpcHost); LLM calls go through the
+host-side broker (B2b-1) behind a default-DENY credential policy (C1), and every
+sandboxed run leaves ONE aggregated, sanitized audit record (C2). See
+docs/design/agent-sandbox-architecture.md.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import subprocess
+import uuid
+
+logger = logging.getLogger("agentnode.agent_sandbox")
+
+
+def _agent_sandbox_enabled() -> bool:
+    """Default OFF. Env ``AGENTNODE_AGENT_SANDBOX`` wins, else config
+    ``agent_sandbox.enabled`` in ~/.agentnode/config.json."""
+    if os.environ.get("AGENTNODE_AGENT_SANDBOX", "").strip().lower() in ("1", "true"):
+        return True
+    try:
+        from agentnode_sdk.config import load_config
+        section = (load_config() or {}).get("agent_sandbox") or {}
+        return bool(section.get("enabled", False))
+    except Exception:
+        return False
+
+
+def _audit_sandbox_run(slug, *, trust_level, run_id, success, reason,
+                       policy=None, usage=None, events=None) -> None:
+    """C2: ONE aggregated audit record per sandboxed agent run (reuses
+    ``policy.audit_decision``; no new storage). Sanitized by construction:
+    fixed reason codes, counters, and caps only — never prompts, keys, raw
+    provider errors, or agent-authored error text. Never crashes the caller."""
+    try:
+        from agentnode_sdk.policy import PolicyResult, audit_decision
+
+        llm = None
+        if policy is not None:
+            llm = {
+                "enabled": policy.enabled,
+                "max_calls": policy.max_calls,
+                "max_input_chars": policy.max_input_chars,
+                "max_output_chars": policy.max_output_chars,
+                "allowed_models": (sorted(policy.allowed_models)
+                                   if policy.allowed_models is not None else None),
+            }
+            llm.update(usage or {})
+        ev = events or []
+        audit_decision(
+            PolicyResult(action="allow" if success else "deny",
+                         reason=reason, source="agent_sandbox"),
+            "agent_run",
+            slug,
+            trust_level=trust_level,
+            run_id=run_id,
+            extra={
+                "sandbox": True,
+                "llm": llm,
+                "tool_calls": sum(1 for e in ev if e and e[0] == "run_tool"),
+                "tool_refusals": sum(
+                    1 for e in ev if e and e[0] in ("refused_allowlist", "refused_limit")),
+            },
+        )
+    except Exception:
+        logger.debug("Failed to audit sandboxed agent run: %s", slug, exc_info=True)
+
+
+def run_agent_sandboxed(slug, entry, agent_config, *, goal=None, run_id=None, **kwargs):
+    """Run a community agent's entrypoint inside the sandbox. Returns a
+    RunToolResult. Fail-closed on a missing/stale volume or no runtime — never
+    runs the agent on the host."""
+    from agentnode_sdk.models import RunToolResult
+    from agentnode_sdk.sandbox import get_default_backend, sandbox_volume_name
+    from agentnode_sdk.sandbox.agent_container_wrapper import WRAPPER_SOURCE
+    from agentnode_sdk.sandbox.agent_rpc import AgentRpcHost
+    from agentnode_sdk.sandbox.types import MountSpec, ProcessSpec
+
+    def _fail(error: str, mode: str = "sandbox_unavailable",
+              reason_code: str = "fail_closed") -> "RunToolResult":
+        # C2: fail-closed refusals get an audit record too (deny + fixed code).
+        _audit_sandbox_run(slug, trust_level=(entry or {}).get("trust_level"),
+                           run_id=run_id, success=False, reason=reason_code)
+        return RunToolResult(success=False, error=error, mode_used=mode, run_id=run_id)
+
+    agent_config = agent_config or {}
+    entrypoint = agent_config.get("entrypoint", "")
+    if not entrypoint:
+        return _fail(f"Agent '{slug}' has no entrypoint defined.",
+                     mode="agent_sandbox", reason_code="no_entrypoint")
+
+    limits = agent_config.get("limits") or {}
+    max_tool_calls = limits.get("max_tool_calls", 40)
+    timeout = float(limits.get("max_runtime_seconds", 180))
+    allowed = (agent_config.get("tool_access") or {}).get("allowed_packages")
+    effective_goal = goal or agent_config.get("goal", "")
+
+    # Volume gate — mirror python_runner._run_container; never trust the lockfile
+    # blindly. The community agent's code was built into this volume at install.
+    expected_vol = sandbox_volume_name(slug, entry.get("version"), entry.get("artifact_hash"))
+    if not entry.get("sandboxed") or entry.get("sandbox_volume") != expected_vol:
+        return _fail(
+            f"Agent sandbox volume missing or stale — reinstall '{slug}' "
+            f"(run: agentnode install {slug}).",
+            reason_code="volume_missing",
+        )
+
+    backend = get_default_backend()
+    avail = backend.check_available()
+    if not avail.available:
+        return _fail(
+            "Agent execution requires a container runtime + the pinned image. "
+            f"{avail.reason or 'none available'} — refusing to run community agent "
+            "code on the host.",
+            reason_code="backend_unavailable",
+        )
+
+    runtime = avail.backend or "docker"
+    try:
+        insp = subprocess.run(
+            [runtime, "volume", "inspect", expected_vol],
+            capture_output=True, timeout=10,
+        )
+    except Exception as exc:
+        return _fail(f"Could not verify sandbox volume: {exc}",
+                     reason_code="volume_inspect_failed")
+    if insp.returncode != 0:
+        return _fail(f"Agent sandbox volume missing — reinstall '{slug}'.",
+                     reason_code="volume_missing")
+
+    safe = re.sub(r"[^a-zA-Z0-9_.-]", "-", slug)[:40] or "agent"
+    spec = ProcessSpec(
+        command=["python", "-c", WRAPPER_SOURCE],
+        network="none",
+        env={"PYTHONPATH": "/pack"},
+        mounts=[MountSpec(src=expected_vol, dst="/pack", read_only=True)],
+        clean_home=True,
+        interactive=True,
+        name=f"agentnode-agent-{safe}-{uuid.uuid4().hex[:8]}",
+    )
+
+    # B2a: STRICT host-side allowlist (the agent's declared tool_access). A
+    # community agent with no declared allowlist gets no tool access — broadening
+    # "unrestricted" community agents is a later decision.
+    # B2b-1: LLM calls go through the host-side broker (the provider key stays on
+    # the host, never in the container).
+    # C1: that broker is wrapped by a default-DENY credential policy — the agent
+    # reaches the host LLM key only if it declared llm_access.enabled, and the
+    # host-config ceiling (agent_sandbox.llm) always wins. Refusals come back as
+    # graceful per-call errors (the agent can catch them), never a host fallback.
+    from agentnode_sdk.runtimes.agent_llm_broker import host_llm_broker
+    from agentnode_sdk.runtimes.agent_llm_policy import make_policy_broker, resolve_llm_policy
+
+    try:
+        from agentnode_sdk.config import load_config
+        host_cfg = load_config() or {}
+    except Exception:
+        host_cfg = {}
+    policy = resolve_llm_policy(agent_config, host_cfg)
+    policy_broker = make_policy_broker(policy, host_llm_broker)
+
+    # Fail-closed: a sandbox-START failure (e.g. the runtime vanished between the
+    # availability check and the launch) returns a clean sandbox_unavailable —
+    # it never raises out and never falls back to the host.
+    try:
+        session = backend.open_agent_session(spec)
+    except Exception as exc:
+        return _fail(f"Could not start the agent sandbox: {exc}",
+                     reason_code="session_start_failed")
+
+    host = AgentRpcHost(
+        allowed_packages=allowed or [],
+        max_tool_calls=max_tool_calls,
+        llm_broker=policy_broker,
+    )
+    try:
+        out = host.run(
+            session,
+            init={"entrypoint": entrypoint, "goal": effective_goal, "kwargs": kwargs},
+            timeout=timeout,
+        )
+    except Exception as exc:
+        _audit_sandbox_run(slug, trust_level=entry.get("trust_level"), run_id=run_id,
+                           success=False, reason=f"host_loop_error: {type(exc).__name__}",
+                           policy=policy, usage=policy_broker.usage, events=host.events)
+        return RunToolResult(
+            success=False, error=f"Sandboxed agent failed: {exc}",
+            mode_used="agent_sandbox", run_id=run_id,
+        )
+    finally:
+        session.close()
+
+    res = out.get("result") or {}
+    events = out.get("events") or []
+    if res.get("ok"):
+        _audit_sandbox_run(slug, trust_level=entry.get("trust_level"), run_id=run_id,
+                           success=True, reason="agent_completed",
+                           policy=policy, usage=policy_broker.usage, events=events)
+        return RunToolResult(success=True, result=res.get("value"), mode_used="agent_sandbox", run_id=run_id)
+    _audit_sandbox_run(slug, trust_level=entry.get("trust_level"), run_id=run_id,
+                       success=False, reason="agent_error",
+                       policy=policy, usage=policy_broker.usage, events=events)
+    return RunToolResult(
+        success=False, error=res.get("error", "sandboxed agent failed"),
+        mode_used="agent_sandbox", run_id=run_id,
+    )