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

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

@@ -1,5 +1,87 @@
 # Changelog
 
+## 0.12.1 — agent_sandbox config fix
+
+### Fixed
+
+- **`agent_sandbox` config section was stripped during `load_config()`.** The
+  config loader rebuilt the file from defaults and silently dropped a
+  hand-written `agent_sandbox` section, so the documented
+  `agent_sandbox.enabled: true` config path never took effect (only the
+  `AGENTNODE_AGENT_SANDBOX` env var worked), and the host LLM ceiling
+  (`agent_sandbox.llm.*`) never reached policy resolution. Both now survive
+  loading; the nested `llm` ceiling is passed through verbatim.
+- **`agentnode config set agent_sandbox.enabled true|false` now works** (the
+  key was missing from the allowed-keys whitelist) and stores a **real
+  boolean** — previously a stored string `"false"` would have been truthy,
+  i.e. read as enabled.
+
+### Upgrade Notes
+
+- No breaking changes. No behavior change unless you use the `agent_sandbox`
+  config path; the env var `AGENTNODE_AGENT_SANDBOX` behaves exactly as
+  before. The agent sandbox remains **default OFF**.
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.11.4
+Version: 0.12.1
 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.1}/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.1"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",

{agentnode_sdk-0.11.4 → agentnode_sdk-0.12.1}/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.11.4 → agentnode_sdk-0.12.1}/agentnode_sdk/config.py

@@ -41,6 +41,9 @@ DEFAULTS: dict[str, Any] = {
         "compute": "allow",
         "unknown": "prompt",
     },
+    "agent_sandbox": {
+        "enabled": False,
+    },
 }
 
 VALID_VALUES: dict[str, tuple[str, ...]] = {
@@ -61,6 +64,7 @@ VALID_VALUES: dict[str, tuple[str, ...]] = {
     "guard.read": ("allow", "prompt", "deny"),
     "guard.compute": ("allow", "prompt", "deny"),
     "guard.unknown": ("allow", "prompt", "deny"),
+    "agent_sandbox.enabled": ("true", "false"),
 }
 
 
@@ -82,6 +86,7 @@ CONFIG_DESCRIPTIONS: dict[str, str] = {
     "guard.read": "Guard policy for tools that read data",
     "guard.compute": "Guard policy for tools that perform computation",
     "guard.unknown": "Guard policy for tools with unknown action type",
+    "agent_sandbox.enabled": "Route community (verified/unverified) agents through the container sandbox",
 }
 
 
@@ -138,6 +143,14 @@ def _merge_defaults(data: dict) -> dict[str, Any]:
         for extra_key in ("rate_limits", "agent_overrides", "tool_overrides"):
             if extra_key in data["guard"]:
                 cfg["guard"][extra_key] = data["guard"][extra_key]
+    if isinstance(data.get("agent_sandbox"), dict):
+        if "enabled" in data["agent_sandbox"]:
+            cfg["agent_sandbox"]["enabled"] = data["agent_sandbox"]["enabled"]
+        # The nested llm ceiling (max_calls/max_input_chars/max_output_chars/
+        # allowed_models/enabled) holds ints/lists — pass it through verbatim,
+        # like the guard extra keys above.
+        if isinstance(data["agent_sandbox"].get("llm"), dict):
+            cfg["agent_sandbox"]["llm"] = data["agent_sandbox"]["llm"]
     return cfg
 
 
@@ -201,7 +214,7 @@ def set_value(cfg: dict[str, Any], key: str, value: str) -> dict[str, Any]:
             f"Allowed: {', '.join(allowed)}"
         )
 
-    bool_keys = ("credentials.require_before_auto_install",)
+    bool_keys = ("credentials.require_before_auto_install", "agent_sandbox.enabled")
     actual_value: Any = value.lower() == "true" if key in bool_keys else value.lower()
 
     parts = key.split(".")

agentnode_sdk-0.12.1/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.1/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.1}/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,