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

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

@@ -1,5 +1,83 @@
 # 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 publish` now asks for confirmation before publishing.** After the
+  preview, the command prompts `Publish <pkg>@<version> to <registry>? [y/N]`
+  (default No) and only uploads on explicit `y`. A new `--yes`/`-y` flag skips
+  the prompt for CI/automation. `--dry-run` is unchanged (never prompts, never
+  publishes). Prevents accidental publishes of the wrong package/version/folder.
+
+### BREAKING / Upgrade Notes
+
+- **Non-interactive publish now requires `--yes`.** Previously `agentnode publish`
+  in a non-interactive context (CI, piped stdin, or `AGENTNODE_NON_INTERACTIVE=1`)
+  uploaded silently. It now **refuses** without `--yes` and exits non-zero.
+  Automation that publishes must add `--yes`. Interactive use is unaffected
+  beyond the new prompt.
+
 ## 0.11.3 — Test hygiene + multi-tool run guidance
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.11.3
+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.3 → 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.3"
+__version__ = "0.12.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",

{agentnode_sdk-0.11.3 → agentnode_sdk-0.12.0}/agentnode_sdk/cli/main.py

@@ -154,6 +154,7 @@ def main(argv: list[str] | None = None) -> int:
     publish_parser.add_argument("--dry-run", action="store_true", help="Validate and build without uploading")
     publish_parser.add_argument("--skip-validate", action="store_true", help="Continue despite validation errors")
     publish_parser.add_argument("--token", default=None, help="API key (default: AGENTNODE_API_KEY env)")
+    publish_parser.add_argument("--yes", "-y", action="store_true", help="Skip the confirmation prompt (required for non-interactive/CI publish)")
 
     # record-cases
     record_parser = sub.add_parser("record-cases", help="Record VCR cassettes for API verification cases")
@@ -338,7 +339,7 @@ def main(argv: list[str] | None = None) -> int:
             return commands.cmd_verify_local(args.path)
         if args.command == "publish":
             from agentnode_sdk.cli.publish import cmd_publish
-            return cmd_publish(args.path, dry_run=args.dry_run, skip_validate=args.skip_validate, token=args.token)
+            return cmd_publish(args.path, dry_run=args.dry_run, skip_validate=args.skip_validate, token=args.token, yes=args.yes)
         if args.command == "record-cases":
             return commands.cmd_record_cases(args.path, strict=args.strict)
         if args.command == "inspect":

{agentnode_sdk-0.11.3 → agentnode_sdk-0.12.0}/agentnode_sdk/cli/publish.py

@@ -286,12 +286,38 @@ def _post_publish(
     }
 
 
+def _confirm_publish(
+    pkg_id: str, version: str, registry: str, *, yes: bool, interactive: bool
+) -> bool:
+    """Final consent gate before an external publish. Returns True to proceed.
+
+    - ``yes``: explicit bypass for CI/automation → proceed.
+    - not ``interactive``: refuse — never publish non-interactively without --yes.
+    - interactive: prompt ``[y/N]``, default No.
+    """
+    if yes:
+        return True
+    if not interactive:
+        print(
+            "  Refusing to publish non-interactively. "
+            "Re-run with --yes to confirm in CI/automation.",
+            file=sys.stderr,
+        )
+        return False
+    answer = input(f"  Publish {pkg_id}@{version} to {registry}? [y/N] ").strip().lower()
+    if answer in ("y", "yes"):
+        return True
+    print("  Publish cancelled.")
+    return False
+
+
 def cmd_publish(
     path_str: str,
     *,
     dry_run: bool = False,
     skip_validate: bool = False,
     token: str | None = None,
+    yes: bool = False,
 ) -> int:
     """Publish a package to the AgentNode registry."""
     from agentnode_sdk.cli.validate import validate_package_dir
@@ -389,6 +415,19 @@ def cmd_publish(
         )
         return 1
 
+    # Publish confirm gate — publish is an external, hard-to-undo action.
+    # Detect interactivity robustly (CI/pipes have a non-TTY stdin even without
+    # AGENTNODE_NON_INTERACTIVE set); non-interactive requires explicit --yes.
+    registry = _resolve_api_base().replace("https://", "").replace("http://", "")
+    interactive = sys.stdin.isatty() and os.environ.get(
+        "AGENTNODE_NON_INTERACTIVE", ""
+    ).lower() not in ("true", "1")
+    if not _confirm_publish(pkg_id, version, registry, yes=yes, interactive=interactive):
+        # interactive decline = clean cancel (0); non-interactive without --yes
+        # = refusal (1). When yes=True the gate always proceeds, so we never land
+        # here in that case.
+        return 0 if interactive else 1
+
     try:
         sig_block = _sign_for_publish(pkg_id, manifest, artifact_bytes)
         manifest["_signatures"] = {"publisher": [sig_block]}

{agentnode_sdk-0.11.3 → 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.3 → 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,