agentnode-sdk 0.24.1__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.1 → agentnode_sdk-0.25.0}/CHANGELOG.md

@@ -1,5 +1,92 @@
 # 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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentnode-sdk
-Version: 0.24.1
+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.1 → 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.
+"""

agentnode_sdk-0.25.0/agentnode_sdk/access/client.py

@@ -0,0 +1,191 @@
+"""How something on the USER's machine reaches the sandbox: over the authenticated API.
+
+`MANAGED-ACCESS-DECISION-0001` settled this and it is the part worth not forgetting. The CLI, the
+stdio MCP bridge and the SDKs all run where the user is. Anything they enforce is advice: the
+person they are protecting the sandbox from is the person who can edit them. So they get no
+in-process shortcut, no direct `dispatch()` call, and no access to `GatewayState`, the worker or
+the runtime -- they speak HTTP to the gateway exactly as a stranger would, and the answer they get
+is the answer anybody would get.
+
+What lives here is therefore a transport and nothing else: take an operation and some parameters,
+present the device's token, and hand back what came out. Every decision was made on the other end.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from agentnode_sdk.access import contract, rest
+
+
+class TheSandboxRefused(Exception):
+    """A refusal, carried back with its name intact so a caller can branch on it."""
+
+    def __init__(self, refusal: str, because: str, what_to_do: str = "") -> None:
+        super().__init__(because)
+        self.refusal = refusal
+        self.because = because
+        self.what_to_do = what_to_do
+
+    def in_words(self) -> str:
+        said = self.because
+        if self.what_to_do:
+            said += "\n" + self.what_to_do
+        return said
+
+
+class Sandbox:
+    """A sandbox somewhere, reached the way anybody reaches it."""
+
+    def __init__(self, base: str, token: str, opener=None, timeout: float = 60.0) -> None:
+        self.base = base.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        #: Supplied by a caller that pins a certificate. Absent here rather than reimplemented:
+        #: pinning already exists in `gateway/pinning.py` and a second version of it would be a
+        #: second thing to get wrong.
+        self.opener = opener
+
+    def ask(self, operation: str, **params):
+        """Carry out an operation, or raise the refusal it came back with."""
+        op = contract.find(operation)
+        path = self.base + rest.NAMESPACE + operation.replace(".", "/")
+        method = "POST" if (op is None or op.changes or op.params) else "GET"
+        body = json.dumps(params).encode("utf-8") if method == "POST" else None
+        request = urllib.request.Request(path, data=body, method=method)
+        request.add_header("Content-Type", "application/json")
+        request.add_header(rest.SPEAKS_HEADER, contract.PROTOCOL_VERSION)
+        if self.token:
+            request.add_header(rest.TOKEN_HEADER, self.token)
+        opener = self.opener.open if self.opener is not None else urllib.request.urlopen
+        try:
+            with opener(request, timeout=self.timeout) as answer:
+                return json.loads(answer.read().decode("utf-8") or "{}")
+        except urllib.error.HTTPError as refused:
+            raise _as_refusal(refused) from None
+        except urllib.error.URLError as unreachable:
+            raise TheSandboxRefused(
+                "sandbox_unavailable",
+                "Could not reach the sandbox at %s: %s" % (self.base, unreachable.reason),
+                "Check that it is running and that this machine can reach it.") from None
+
+    def speak_mcp(self, message: dict) -> dict | None:
+        """Send one JSON-RPC message to this sandbox's MCP endpoint and return its answer.
+
+        Raw, not translated. The gateway already speaks MCP; a second translation on this side
+        would be a second thing to keep in step, and it was one: the bridge used to rebuild MCP
+        out of REST calls, so the gateway recorded the channel as `rest` while the caller was an
+        MCP client. An approval given for MCP could then never be spent, which is how the most
+        prominent option in the console -- Claude Code or Codex on my machine -- could not
+        complete a job at all.
+        """
+        request = urllib.request.Request(self.base + rest.MCP_PATH,
+                                         data=json.dumps(message).encode("utf-8"), method="POST")
+        request.add_header("Content-Type", "application/json")
+        request.add_header(rest.SPEAKS_HEADER, contract.PROTOCOL_VERSION)
+        if self.token:
+            request.add_header(rest.TOKEN_HEADER, self.token)
+        opener = self.opener.open if self.opener is not None else urllib.request.urlopen
+        try:
+            with opener(request, timeout=self.timeout) as answer:
+                body = answer.read().decode("utf-8")
+        except urllib.error.HTTPError as refused:
+            raise _as_refusal(refused) from None
+        except urllib.error.URLError as unreachable:
+            raise TheSandboxRefused(
+                "sandbox_unavailable",
+                "Could not reach the sandbox at %s: %s" % (self.base, unreachable.reason),
+                "Check that it is running and that this machine can reach it.") from None
+        return json.loads(body) if body.strip() else None
+
+    # -- the journey, named the way a person would say it ------------------------------------
+
+    def capabilities(self):
+        return self.ask("capabilities")
+
+    def prepare(self, **what):
+        return self.ask("prepare", **what)
+
+    def submit(self, **what):
+        return self.ask("submit", **what)
+
+    def status(self, run_id: str):
+        return self.ask("status", run_id=run_id)
+
+    def result(self, run_id: str):
+        return self.ask("result", run_id=run_id)
+
+    def cancel(self, run_id: str):
+        return self.ask("cancel", run_id=run_id)
+
+    def usage(self):
+        return self.ask("usage")
+
+    def devices(self):
+        return self.ask("devices.list")
+
+    def revoke(self, device_id: str):
+        return self.ask("devices.revoke", device_id=device_id)
+
+
+def _as_refusal(refused) -> TheSandboxRefused:
+    try:
+        answer = json.loads(refused.read().decode("utf-8") or "{}")
+    except (ValueError, UnicodeDecodeError):
+        answer = {}
+    return TheSandboxRefused(
+        str(answer.get("refused") or "sandbox_unavailable"),
+        str(answer.get("because") or ("the sandbox answered %s" % refused.code)),
+        str(answer.get("what_to_do") or ""))
+
+
+# ---------------------------------------------------------------- the local MCP bridge
+
+
+def bridge(sandbox: Sandbox, incoming, outgoing) -> None:
+    """Speak MCP on a pipe, and forward every call over the authenticated API.
+
+    For programs that will only talk to a local MCP server. It is a relay and holds no authority
+    of its own: every message is forwarded to the sandbox's own MCP endpoint, so the tool list,
+    the refusals and the wording are the sandbox's, not this process's. A tool the device may not
+    use never appears, and calling one anyway is refused at the far end.
+
+    FORWARDED, not translated. This used to rebuild MCP out of REST operations, which meant the
+    gateway saw `rest` while the caller was an MCP client -- so an approval given for MCP could
+    never be spent, and the console's most prominent option could not finish a job. A relay that
+    changes what channel you appear to be on is not a relay.
+    """
+    for line in incoming:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            message = json.loads(line)
+        except ValueError:
+            _write(outgoing, {"jsonrpc": "2.0", "id": None,
+                              "error": {"code": -32700, "message": "that is not JSON"}})
+            continue
+        reply = _forward(sandbox, message)
+        if reply is not None:
+            _write(outgoing, reply)
+
+
+def _forward(sandbox: Sandbox, message: dict):
+    """Hand one message to the sandbox and give back what it said."""
+    method = str(message.get("method") or "")
+    if message.get("id") is None and method.startswith("notifications/"):
+        return None
+    try:
+        return sandbox.speak_mcp(message)
+    except TheSandboxRefused as refusal:
+        # Reaching the sandbox failed, which is not the same as the sandbox refusing a call. It
+        # is reported as a transport error so a client retries rather than telling a person their
+        # job was rejected.
+        return {"jsonrpc": "2.0", "id": message.get("id"),
+                "error": {"code": -32000, "message": refusal.in_words()}}
+
+
+def _write(outgoing, message) -> None:
+    outgoing.write(json.dumps(message) + "\n")
+    outgoing.flush()