agentnode-sdk 0.24.0__tar.gz → 0.25.0__tar.gz

agentnode_sdk-0.25.0/.gitignore

@@ -0,0 +1,85 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Node
+node_modules/
+cli/dist/
+
+# Next.js
+web/.next/
+web/out/
+
+# Environment & Secrets
+.env
+.env.local
+.env.production
+.pypirc
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+*.tar.gz
+*.whl
+
+# Test score artifacts
+.artifacts/
+
+# Spec documents
+*.docx
+
+# Screenshots & temp files
+*.png
+screenshots/
+test-screenshots/
+spec_extracted.txt
+calendar.ics
+events.json
+
+# Playwright
+.playwright-mcp/
+
+# Claude Code
+.claude/
+
+# Internal growth / marketing content
+growth/
+backend/.next/
+kwfinder-*.md
+packages_dump.json
+snapshot_nonowner.txt
+seo/
+backend/scripts/enrichment_*.json
+
+# Internal documentation (not for GitHub)
+internal/
+
+# Internal ops scripts (crawl, enrichment, import)
+scripts/crawl_*.py
+scripts/enrich_*.py
+scripts/import_candidates.py
+scripts/.mcp_cache/
+candidates*.json
+*.lock.lk
+
+# Counter-check and exercise output: evidence for a review bundle, not source.
+sdk/remote-worker-counter-check-results/

{agentnode_sdk-0.24.0 → agentnode_sdk-0.25.0}/CHANGELOG.md

@@ -1,5 +1,148 @@
 # Changelog
 
+## 0.25.0 — refuse what cannot be enforced
+
+A pre-1.0 security release. Several things 0.24.1 did quietly -- run a pack with an open network because
+its network level was unknown, start a run on a network that could not show it had no route out, report
+a conformance boundary as passed when it could not be measured -- are now refused or reported as not
+checked. That is what makes the breaking changes below; each is listed with what to do.
+
+### Breaking changes since 0.24.1
+
+They were measured against the published 0.24.1 wheel: the public API, the CLI and the behaviour tests
+of 0.24.1 were run against this tree. Nothing else in the public API, the signatures, the defaults or
+the command line was removed or changed.
+
+- **Python 3.13 and newer are no longer supported.** `requires-python` is now `>=3.10,<3.13`. An
+  installer on Python 3.13 or 3.14 is not offered this release and stays on 0.24.1.
+- **Network permissions are a contract.** `permissions.network_level` must be one of:
+  - `none`;
+  - `unrestricted`;
+  - `restricted`, which needs a non-empty `allowed_domains`.
+
+  A pack declaring `full`, an unknown value, or `restricted` without domains is refused and nothing
+  runs. 0.24.1 ran such packs with network access.
+- **A network meant to have no route out must show that it is internal.** If the container runtime
+  does not report it, the run is refused rather than started.
+- **Conformance checks say `not_checked`** where a boundary cannot be measured on the host, instead of
+  a pass or a fail.
+- `agentnode_sdk.conformance.runner.TIMEOUT_RC` is now `SUPERSEDED_TIMEOUT_RC`; there is no alias.
+  A timeout no longer has an exit code: test `Outcome.reason == agentnode_sdk.gateway.protocol.TIMED_OUT`
+  instead of comparing the code with -1. An alias would import and then never match, so a timeout would
+  pass for an ordinary ending. Reading `runner.TIMEOUT_RC` raises an `AttributeError` that says this.
+
+### Migrating from 0.24.1
+
+1. **Python.** Use Python 3.10, 3.11 or 3.12. On 3.13 or 3.14 pip does not offer 0.25.0 and keeps
+   0.24.1; pin `agentnode-sdk==0.24.1` there if you need a stable choice.
+2. **Pack network permission.** In `agentnode.yaml` it is `permissions.network.level` (with
+   `permissions.network.allowed_domains`); an installed entry carries it as `permissions.network_level`
+   and `permissions.allowed_domains`.
+   - Missing or empty means `none` (no network), as before.
+   - `full` and `limited` are refused, not translated. Write `unrestricted` if the pack really needs any
+     destination, or `restricted` with `allowed_domains`.
+   - `restricted` needs at least one domain, and each must be a real host name: no IP literal, no
+     `localhost`, no single-label name.
+   - Values are read case-insensitively; anything else is refused with the reason before anything runs.
+   - `agentnode validate` does not apply this rule yet (it only warns about broad network access): a
+     pack that validates can still be refused when it runs. Check the level by hand before publishing.
+3. **Container runtime.** A run that asks for no network now needs a runtime that reports the network
+   it created as internal. If yours does not, the run is refused with the reason; it is not started
+   with a route out.
+4. **Conformance reports.** Treat `not_checked` as its own outcome. It is neither a pass nor a fail:
+   the boundary could not be measured on that host.
+5. **Timeouts in your own code.** Replace `rc == TIMEOUT_RC` with
+   `outcome.reason == agentnode_sdk.gateway.protocol.TIMED_OUT`. The exit code of a stopped run is
+   `None`. `SUPERSEDED_TIMEOUT_RC` (-1) exists only for reading old reports.
+6. **`mcp` dependency.** The bound is now `mcp>=1.0.0,<3`, so an environment with mcp 2.x installs
+   without a conflict.
+
+### Added
+
+- **Remote MCP:** `agentnode serve` serves on mcp 1.x and 2.x (`mcp>=1.0.0,<3`), offers the pack
+  tools and the platform tools, and `--packs` limits what is exposed. A tool error is a failure
+  result.
+- **Website to gateway identity link.** The website signs a single-use link, valid for two minutes.
+  The gateway redeems it with `POST /v1/link`; on the device this is
+  `agentnode remote connect ... --link`. It is inactive until the website's signing key is set.
+- **Per-account ceilings** on a gateway (`--account-runs-per-window`, `--account-lifetime-runs`,
+  `--trial`). Deleting an account clears its ceilings, and an account export carries them.
+- **Self-hosted gateway as a documented beta path.** The gateway refuses to start unpinned unless
+  `AGENTNODE_ALLOW_UNPINNED` is set.
+- **A paired worker rollback needs the control plane's signed statement** (P13). An operator's
+  assertion is no longer enough.
+- **The CLI:** a failed run says why and exits 1, and a dashboard API key is sent as `X-API-Key`.
+- **`agentnode validate` and `agentnode publish` take `--manifest <file>` and `--json`.** The manifest
+  may be `.yaml`, `.yml` or `.json` and need not be called `agentnode.yaml` (publish packs it under
+  that name). `--json` prints one JSON document on stdout. Without the new options both commands
+  behave exactly as before.
+
+### Fixed
+
+- **An edge refusal closes in order,** so its answer reaches a client whose request the edge left
+  unread. Before, the connection could end in a reset.
+
+### Not yet true
+
+- **A worker on its own machine** was accepted by cross-host run r3 for an earlier build (df821f65).
+  The current build was **not** accepted by r4. r5 has not run.
+
+## 0.24.1 — the sandbox does what it said
+
+Three defects in the local sandbox runtime, found by the backend conformance suite (EM-3B)
+measuring a real container rather than reading its configuration. Each is a case where
+AgentNode reported a property it was not enforcing.
+
+### Fixed
+
+- **A wall-clock timeout now ends the payload.** It killed the `docker run` client, which is
+  a pipe to a daemon that owns the process — so the SDK reported a timeout while the
+  container kept running, and `--rm` never removed it because it never exited. Every run now
+  carries an exact identity (a unique name *and* a cidfile); a timeout removes that exact
+  container, waits, and verifies that neither the id nor the name remains. If any of that
+  cannot be shown, `SandboxContainmentError` is raised instead of the ordinary timeout
+  result: a stop nobody could verify is not a stop. Nothing outside the run being stopped is
+  ever addressed, and an identity in doubt stops the removal rather than guessing.
+- **The declared memory ceiling now binds.** `--memory` was passed without `--memory-swap`,
+  and a runtime with only the first set grants a swap allowance of twice the limit — the
+  suite watched a 768 MiB allocation finish with exit code 0 under a 512 MiB "limit". The
+  two are now equal, so the total of memory and swap *is* the limit. Whether an engine can
+  account for swap at all is recorded from `docker info` rather than assumed, so a report can
+  say the ceiling is unproven on that engine instead of resting on the flag having been
+  passed.
+- **A refusal now carries a way out.** It said `no container runtime (docker or podman)
+  found on PATH` and nothing more. There were also two answers to the same question — the
+  SDK's bare sentence and the CLI doctor's structured checks — and only one of them ever had
+  a next step. Both now render one classifier, which distinguishes *not installed*, *not
+  running*, *not permitted*, *an engine in the wrong mode* and *a device where no local
+  sandbox is possible*, and offers only actions that exist on the platform in front of you,
+  each followed by the check that tells you whether it worked. Joining the `docker` group is
+  deliberately not among them: it is administrator-equivalent power on the machine.
+
+### Changed
+
+- `SandboxAvailability` carries `probe_error`, `engine_os` and `memory_limit_enforceable`;
+  `check_available(force=True)` re-asks rather than returning the cached answer, which is what
+  a re-check after a fix needs.
+- One-shot sandboxed runs are now named and labelled like the long-lived ones. Nothing
+  filters on that label; it makes a run identifiable, which is the point.
+
+### Not fixed in this release
+
+- **Declared network levels are still not distinguished from one another.** A toolpack that
+  declares `restricted` receives the same open container network as one that declares
+  `unrestricted`: six recognised level names all map to the engine's default bridge. An unknown or
+  missing level is still correctly isolated (`--network none`), so this is not a case of an
+  unrecognised value being let through — the recognised names simply do not differ in what they
+  grant. The risk score meanwhile rates `internal` below `external`, which points the opposite way
+  from what the runtime does.
+
+  This release deliberately does not correct it. The correction requires a declared domain
+  allowlist in the package manifest, registry validation for it, and a refusal for packages that
+  ask for `restricted` without one — a behaviour change that refuses packages which work today,
+  and too large to carry inside a patch that exists to get two proven runtime fixes to people.
+  It ships separately, at a version that reflects the break.
+
 ## 0.24.0 — The container is the boundary
 
 This release makes the execution boundary real rather than advisory. Third-party code

{agentnode_sdk-0.24.0 → agentnode_sdk-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentnode-sdk
-Version: 0.24.0
+Version: 0.25.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
@@ -13,11 +13,11 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.10
+Requires-Python: <3.13,>=3.10
 Requires-Dist: cryptography>=41.0
 Requires-Dist: httpx>=0.25
 Requires-Dist: keyring>=24
-Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: mcp<3,>=1.0.0
 Requires-Dist: packaging>=21
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev

agentnode_sdk-0.25.0/agentnode_sdk/__init__.py

@@ -0,0 +1,155 @@
+"""AgentNode Python SDK — discover, resolve, and install AI agent capabilities."""
+
+# THE EXCEPTION TYPES FIRST, and outside the guard below, because they need nothing but the
+# standard library and the refusal this module may have to raise has to be a real AgentNodeError
+# rather than something invented on the spot.
+from agentnode_sdk.exceptions import (
+    AgentNodeError,
+    AgentNodeToolError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+#: WHICH DEPENDENCY THIS INSTALLATION IS MISSING, or "" when nothing is.
+#:
+#: WHY THIS EXISTS. `cli/main.py` does `import agentnode_sdk`, and importing any name of this
+#: package executes this file -- which imports the client, the async client and the installer, each
+#: of which imports `httpx` at module scope. On a host whose install was interrupted after the
+#: package arrived and before its dependencies did, that raised `ModuleNotFoundError` three imports
+#: deep and the WHOLE CLI died before argparse existed. The third beta acceptance measured exactly
+#: that: `agentnode gateway doctor` -- the published way to ask whether a host is ready -- answered
+#: with a traceback. A host that cannot say it is not ready is PR7 of that profile at WARN.
+_MISSING_DEPENDENCY = ""
+# EVERYTHING THAT CAN NEED A THIRD-PARTY PACKAGE, under one guard.
+#
+# `ModuleNotFoundError` ONLY, and re-raised at once when the missing module is one of ours. A
+# missing third-party package means the dependencies never arrived -- an incomplete installation,
+# which this package can report. A missing `agentnode_sdk` submodule means this BUILD is wrong, and
+# swallowing that would hide the one class of error that must never be hidden.
+try:
+    from agentnode_sdk.async_client import AsyncAgentNode
+    from agentnode_sdk.client import AgentNode, AgentNodeClient
+    from agentnode_sdk.config import load_config, config_path, installation_behavior_label
+    from agentnode_sdk.detect import detect_gap
+    from agentnode_sdk.installer import load_tool
+    from agentnode_sdk.skill import load_skill, SkillContext, SkillAsset
+    from agentnode_sdk.models import (
+        CanInstallResult,
+        DetectAndInstallResult,
+        DetectedGap,
+        InstallMetadata,
+        InstallResult,
+        PackageDetail,
+        ResolvedPackage,
+        ResolveResult,
+        RunToolResult,
+        SearchHit,
+        SearchResult,
+        SmartRunResult,
+    )
+    from agentnode_sdk.compatibility import recommend_model
+    from agentnode_sdk.risk_profile import RiskProfile, compute_risk_profile, get_risk_profile
+    from agentnode_sdk.policy import PolicyResult, check_install, check_run
+    from agentnode_sdk.runner import run_tool
+    from agentnode_sdk.runtime import AgentNodeRuntime
+
+    # Convenience aliases
+    Client = AgentNodeClient
+    ToolError = AgentNodeToolError
+except ModuleNotFoundError as _missing:                       # noqa: BLE001
+    _name = str(getattr(_missing, "name", "") or "")
+    if _name.split(".")[0] == "agentnode_sdk":
+        raise
+    _MISSING_DEPENDENCY = _name or str(_missing)
+
+#: THE ONE PLACE THE VERSION IS WRITTEN. `pyproject.toml` builds the wheel's version from this
+#: line rather than carrying its own copy, because it did carry one: the project said 0.25.0
+#: while this said 0.24.1, so the gateway announced 0.24.1 to every client it answered while
+#: running the 0.25.0 build. Two copies of one number drift, and the drift is invisible until
+#: something reports the wrong one.
+__version__ = "0.25.0"
+__all__ = [
+    "AgentNode",
+    "AsyncAgentNode",
+    "AgentNodeClient",
+    "Client",
+    "load_config",
+    "config_path",
+    "installation_behavior_label",
+    "detect_gap",
+    "load_tool",
+    "load_skill",
+    "SkillContext",
+    "SkillAsset",
+    "run_tool",
+    "AgentNodeError",
+    "AgentNodeToolError",
+    "ToolError",
+    "NotFoundError",
+    "AuthError",
+    "RateLimitError",
+    "ValidationError",
+    "PackageDetail",
+    "SearchResult",
+    "SearchHit",
+    "ResolveResult",
+    "ResolvedPackage",
+    "InstallMetadata",
+    "InstallResult",
+    "CanInstallResult",
+    "RunToolResult",
+    "DetectedGap",
+    "DetectAndInstallResult",
+    "SmartRunResult",
+    "AgentNodeRuntime",
+    "PolicyResult",
+    "check_install",
+    "check_run",
+    "recommend_model",
+    "RiskProfile",
+    "compute_risk_profile",
+    "get_risk_profile",
+]
+
+
+def what_this_installation_is_missing() -> str:
+    """The third-party package this installation needs and does not have, or "".
+
+    Read by the readiness paths -- `gateway doctor`, `gateway status`, `worker preflight` -- so that
+    a host whose install was interrupted can SAY SO in words and in a machine-readable form, rather
+    than dying three imports deep on a package nobody asked it about.
+    """
+    return _MISSING_DEPENDENCY
+
+
+if _MISSING_DEPENDENCY:
+    # BIND EVERY PUBLIC NAME THAT DID NOT GET ONE, to something that explains itself.
+    #
+    # Driven by `__all__` rather than by a hand-written list, so the stub set cannot drift from the
+    # public API -- a name added above and forgotten here would be an `AttributeError` on an
+    # incomplete installation instead of the sentence this is for.
+    #
+    # A STUB THAT RAISES, never one that returns something. A silent no-op would be worse than the
+    # traceback it replaces: the traceback at least said what was wrong.
+    def _needs_the_missing_package(_name):
+        def refuse(*_args, **_kwargs):
+            # `AgentNodeError(code, message)`, which is the signature it has. The first version of
+            # this passed one string and the stub raised `TypeError` instead of saying anything.
+            raise AgentNodeError(
+                "installation_incomplete",
+                "%s needs the %r package, which this installation does not have. The install "
+                "was interrupted before its dependencies arrived; re-run the installer for this "
+                "host, or `pip install %s`. Ask this host what it is missing with "
+                "`agentnode gateway doctor`."
+                % (_name, _MISSING_DEPENDENCY, _MISSING_DEPENDENCY))
+        refuse.__name__ = str(_name)
+        refuse.__doc__ = ("Unavailable: this installation is missing %r."
+                          % _MISSING_DEPENDENCY)
+        return refuse
+
+    for _public in __all__:
+        if _public not in globals():
+            globals()[_public] = _needs_the_missing_package(_public)
+    del _public

{agentnode_sdk-0.24.0 → agentnode_sdk-0.25.0}/agentnode_sdk/_agent_pip.py

@@ -274,11 +274,33 @@ for dist in im.distributions():
             "editable": is_editable(dist),
             "has_record": has_record,
             "provides_top": expected_top in tops,
+            # WHERE it really is, so two paths to one directory can be seen as one thing. A venv
+            # with lib64 symlinked to lib puts both on sys.path, and an interpreter that walks
+            # both reports the same installation twice.
+            "where": canon(dip) if dip else "",
         })
     else:
         if expected_top in tops:
             other_top_providers.append(nm or "?")
 
+# ONE INSTALLATION SEEN DOWN TWO PATHS IS ONE INSTALLATION. Deduplicated by the resolved
+# location before anything counts them, because the question `post_verify` asks -- is this
+# installed exactly once -- is about installations and was being answered about paths. Entries
+# with no resolvable location are kept as they are: an unlocatable match is not a duplicate of
+# anything, and silently folding them together would hide the case worth seeing.
+seen = {}
+unique = []
+for m in matches:
+    where = m.get("where") or ""
+    if not where:
+        unique.append(m)
+        continue
+    if where in seen:
+        continue
+    seen[where] = True
+    unique.append(m)
+matches = unique
+
 print(json.dumps({"matches": matches, "other_top_providers": other_top_providers}))
 '''
 

agentnode_sdk-0.25.0/agentnode_sdk/_provenance.py

@@ -0,0 +1,61 @@
+"""Which source this artefact was built from, written INTO it at build time.
+
+A deployment used to be handed a commit and believe it. `deploy-pinned.sh` took the commit as an
+argument and compared it against an expectation only when an optional environment variable
+supplied one, so the answer to "which source is this wheel?" was whatever the caller said.
+`ALPHA-RUNTIME-PIN-0002` named that, and it was right: nothing tied the artefact to a commit.
+
+So the build writes it in. `PROVENANCE_NAME` is part of the package, which means it is part of the
+wheel, which means it is covered by the wheel's digest -- changing the commit changes the artefact.
+A deployment reads it back OUT of the wheel before installing anything and refuses if it is absent
+or disagrees. The operator can still lie to the build; what they can no longer do is hand a
+deployment an artefact and a commit that have nothing to do with each other.
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import zipfile
+
+#: Inside the installed package and inside the wheel, at the same relative path.
+PROVENANCE_NAME = "_provenance.json"
+
+
+def written_beside_this_module() -> pathlib.Path:
+    return pathlib.Path(__file__).resolve().parent / PROVENANCE_NAME
+
+
+def record(commit: str, where: pathlib.Path | None = None) -> pathlib.Path:
+    """Write the commit into the source tree, so the build carries it into the wheel."""
+    path = where or written_beside_this_module()
+    path.write_text(json.dumps({"commit": str(commit or "")}, indent=1) + "\n",
+                    encoding="utf-8")
+    return path
+
+
+def of_this_installation() -> str:
+    """The commit this installed package was built from, or "" when it does not say."""
+    try:
+        said = json.loads(written_beside_this_module().read_text(encoding="utf-8"))
+    except Exception:                                             # noqa: BLE001
+        return ""
+    return str(said.get("commit") or "") if isinstance(said, dict) else ""
+
+
+def of_a_wheel(wheel) -> str:
+    """The commit a wheel was built from, read WITHOUT installing it.
+
+    Before anything is installed is the only moment this is worth asking: a deployment that
+    discovers the artefact is the wrong one after replacing the running code has discovered it
+    too late.
+    """
+    try:
+        with zipfile.ZipFile(str(wheel)) as inside:
+            names = [n for n in inside.namelist()
+                     if n.endswith("agentnode_sdk/" + PROVENANCE_NAME)]
+            if not names:
+                return ""
+            said = json.loads(inside.read(names[0]).decode("utf-8"))
+    except Exception:                                             # noqa: BLE001
+        return ""
+    return str(said.get("commit") or "") if isinstance(said, dict) else ""

agentnode_sdk-0.25.0/agentnode_sdk/access/__init__.py

@@ -0,0 +1,10 @@
+"""How anything reaches AgentNode.
+
+One contract, several transports over it, and no security decision anywhere but the server. What
+lives here is the part that is the same for every client: which systems can reach us at all
+(`compatibility`), and -- as it is built -- the canonical operation contract that MCP, REST, the
+SDK, the CLI and the web client are each a rendering of.
+
+Nothing here is specific to any AI vendor. A provider name may appear in a test or in a
+compatibility record as data; it may not appear in a decision.
+"""