adk-code-mode-sandbox 0.1.0__tar.gz

adk_code_mode_sandbox-0.1.0/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Custom
+.DS_Store

adk_code_mode_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: adk-code-mode-sandbox
+Version: 0.1.0
+Summary: In-sandbox runtime shim for adk-code-mode. Stdlib-only. Installs inside the container image the host runtime launches.
+Project-URL: Documentation, https://github.com/A2ANet/adk-code-mode#readme
+Project-URL: Issues, https://github.com/A2ANet/adk-code-mode/issues
+Project-URL: Source, https://github.com/A2ANet/adk-code-mode
+Author-email: A2A Net <hello@a2anet.com>
+License-Expression: Apache-2.0
+Keywords: adk,code-mode,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ADK Code Mode Sandbox
+
+In-sandbox shim for [`adk-code-mode`](https://github.com/A2ANet/adk-code-mode). The host package launches a container that has this wheel installed, then talks to it over a TCP control connection so model code can call ADK tools that run on the host.
+
+## 📄 License
+
+`adk-code-mode-sandbox` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.
+
+## 🤝 Join the A2A Net Community
+
+A2A Net is a site to find and share AI agents and open-source community. Join to share your A2A agents, ask questions, stay up-to-date with the latest A2A news, be the first to hear about open-source releases, tutorials, and more!
+
+- 🌍 Site: [A2A Net](https://a2anet.com)
+- 🤖 Discord: [Join the Discord](https://discord.gg/674NGXpAjU)

adk_code_mode_sandbox-0.1.0/README.md

@@ -0,0 +1,14 @@
+# ADK Code Mode Sandbox
+
+In-sandbox shim for [`adk-code-mode`](https://github.com/A2ANet/adk-code-mode). The host package launches a container that has this wheel installed, then talks to it over a TCP control connection so model code can call ADK tools that run on the host.
+
+## 📄 License
+
+`adk-code-mode-sandbox` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.
+
+## 🤝 Join the A2A Net Community
+
+A2A Net is a site to find and share AI agents and open-source community. Join to share your A2A agents, ask questions, stay up-to-date with the latest A2A news, be the first to hear about open-source releases, tutorials, and more!
+
+- 🌍 Site: [A2A Net](https://a2anet.com)
+- 🤖 Discord: [Join the Discord](https://discord.gg/674NGXpAjU)

adk_code_mode_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adk-code-mode-sandbox"
+dynamic = ["version"]
+description = "In-sandbox runtime shim for adk-code-mode. Stdlib-only. Installs inside the container image the host runtime launches."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+keywords = ["adk", "code-mode", "sandbox"]
+authors = [
+  { name = "A2A Net", email = "hello@a2anet.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/A2ANet/adk-code-mode#readme"
+Issues = "https://github.com/A2ANet/adk-code-mode/issues"
+Source = "https://github.com/A2ANet/adk-code-mode"
+
+[tool.hatch.version]
+path = "src/adk_code_mode_sandbox/__about__.py"

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+__version__ = "0.1.0"  # x-release-please-version

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+from adk_code_mode_sandbox.__about__ import __version__
+
+__all__ = ["__version__"]

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+from adk_code_mode_sandbox._entry import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/_entry.py

@@ -0,0 +1,155 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Sandbox entry point.
+
+Invoked as ``python -m adk_code_mode_sandbox``. Three control-pipe transports
+are supported, chosen by env var (checked in order):
+
+- ``ADK_CODE_MODE_CONTROL_TCP`` → ``host:port`` TCP endpoint on the host
+  (used by the Docker runtime; works on mac/Windows/Linux uniformly).
+- ``ADK_CODE_MODE_CONTROL_SOCKET`` → Unix domain socket path (used by the
+  in-process test ``FakeRuntime``; broken on Docker Desktop macOS so not
+  used by ``DockerRuntime``).
+- ``ADK_CODE_MODE_CONTROL_FD`` → inherited fd(s). Accepts one fd
+  (bidirectional) or two comma-separated fds (read,write).
+
+Installs the RPC client, announces readiness, then waits for a ``run`` frame.
+On receipt, execs the user code with stdout/stderr on the normal streams and
+any ``tools.*`` calls funnelling through the RPC client.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import traceback
+from typing import Any
+
+from adk_code_mode_sandbox import _rpc_client
+from adk_code_mode_sandbox._rpc_client import RpcClient
+from adk_code_mode_sandbox.protocol import (
+    DoneFrame,
+    ReadyFrame,
+    RunFrame,
+    ShutdownFrame,
+)
+
+CONTROL_FD_ENV = "ADK_CODE_MODE_CONTROL_FD"
+CONTROL_SOCKET_ENV = "ADK_CODE_MODE_CONTROL_SOCKET"
+CONTROL_TCP_ENV = "ADK_CODE_MODE_CONTROL_TCP"
+CONTROL_TOKEN_ENV = "ADK_CODE_MODE_CONTROL_TOKEN"
+TOOLS_DIR_ENV = "ADK_CODE_MODE_TOOLS_DIR"
+WORKDIR_ENV = "ADK_CODE_MODE_WORKDIR"
+TOOLS_DIR = os.environ.get(TOOLS_DIR_ENV, "/tools")
+WORKDIR = os.environ.get(WORKDIR_ENV, "/workspace")
+
+
+def _open_control_streams() -> tuple[Any, Any]:
+    """Open the host control pipe as a (reader, writer) pair."""
+    tcp_endpoint = os.environ.get(CONTROL_TCP_ENV)
+    if tcp_endpoint:
+        host, _, port_s = tcp_endpoint.rpartition(":")
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.connect((host, int(port_s)))
+        token = os.environ.get(CONTROL_TOKEN_ENV, "")
+        sock.sendall(token.encode("ascii") + b"\n")
+        return sock.makefile("rb", buffering=0), sock.makefile("wb", buffering=0)
+    sock_path = os.environ.get(CONTROL_SOCKET_ENV)
+    if sock_path:
+        usock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        usock.connect(sock_path)
+        return usock.makefile("rb", buffering=0), usock.makefile("wb", buffering=0)
+    raw = os.environ.get(CONTROL_FD_ENV, "3")
+    if "," in raw:
+        read_fd_s, write_fd_s = raw.split(",", 1)
+        read_fd, write_fd = int(read_fd_s), int(write_fd_s)
+    else:
+        read_fd = write_fd = int(raw)
+    return (
+        os.fdopen(read_fd, "rb", buffering=0, closefd=False),
+        os.fdopen(write_fd, "wb", buffering=0, closefd=False),
+    )
+
+
+def _prepare_sys_path() -> None:
+    """Make the generated tools directory importable from user code."""
+    if os.path.isdir(TOOLS_DIR):
+        # TOOLS_DIR is the package directory itself (normally /tools), not a
+        # parent that contains tools/. Add the parent so `import tools` resolves
+        # directly to /tools/__init__.py instead of requiring /tools/tools.
+        package_parent = os.path.dirname(os.path.abspath(TOOLS_DIR)) or os.sep
+        if package_parent not in sys.path:
+            sys.path.insert(0, package_parent)
+
+
+def _prepare_workdir() -> None:
+    os.makedirs(WORKDIR, exist_ok=True)
+    os.chdir(WORKDIR)
+
+
+def _make_globals() -> dict[str, Any]:
+    """Build the globals dict for ``exec``. Looks like a normal ``__main__``."""
+    return {
+        "__name__": "__main__",
+        "__doc__": None,
+        "__package__": None,
+        "__loader__": None,
+        "__spec__": None,
+        "__builtins__": __builtins__,
+    }
+
+
+def _run_code(code: str) -> int:
+    """Execute user code. Returns the exit code (0 ok, 1 on exception)."""
+    globs = _make_globals()
+    try:
+        compiled = compile(code, "<code-mode>", "exec")
+    except SyntaxError:
+        traceback.print_exc()
+        return 1
+    try:
+        exec(compiled, globs)
+    except SystemExit as exc:
+        code_val = exc.code
+        if code_val is None:
+            return 0
+        if isinstance(code_val, int):
+            return code_val
+        print(code_val, file=sys.stderr)
+        return 1
+    except BaseException:
+        traceback.print_exc()
+        return 1
+    return 0
+
+
+def main() -> int:
+    reader, writer = _open_control_streams()
+    client = RpcClient(reader=reader, writer=writer)
+    _rpc_client.install(client)
+    _prepare_sys_path()
+    _prepare_workdir()
+
+    client.send(ReadyFrame())
+
+    while True:
+        frame = client.recv()
+        if isinstance(frame, ShutdownFrame):
+            return 0
+        if isinstance(frame, RunFrame):
+            exit_code = _run_code(frame.code)
+            sys.stdout.flush()
+            sys.stderr.flush()
+            client.send(DoneFrame(exit_code=exit_code))
+            continue
+        # Any other frame kind is a host protocol error; keep going but log.
+        print(
+            f"[adk-code-mode-sandbox] unexpected frame kind: {type(frame).__name__}",
+            file=sys.stderr,
+        )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/_rpc_client.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Blocking RPC client used by generated tool stubs inside the sandbox.
+
+All tool stubs funnel through ``call(name, args)``. The global client instance
+is installed by ``_entry`` before user code runs. Stubs import it lazily:
+
+.. code-block:: python
+
+    from adk_code_mode_sandbox._rpc_client import call
+    result = call("slack.send_message", {"channel": "C1", "text": "hi"})
+"""
+
+from __future__ import annotations
+
+from collections import deque
+import threading
+import uuid
+from typing import Any
+
+from adk_code_mode_sandbox.protocol import (
+    Frame,
+    ProtocolError,
+    ToolCallFrame,
+    ToolResultFrame,
+    decode,
+    encode,
+)
+
+
+class ToolError(RuntimeError):
+    """Raised inside the sandbox when a host-side tool call fails."""
+
+    def __init__(self, error_type: str, message: str, trace: str | None = None) -> None:
+        super().__init__(f"{error_type}: {message}")
+        self.error_type = error_type
+        self.trace = trace
+
+
+class RpcClient:
+    """Synchronous, thread-safe RPC client over the sandbox control pipe.
+
+    The control pipe is a pair of unbuffered streams: ``_out`` for frames going
+    to the host and ``_in`` for frames coming back. Both are line-oriented.
+    """
+
+    def __init__(self, *, reader: Any, writer: Any) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._write_lock = threading.Lock()
+        self._state_lock = threading.Lock()
+        self._state_changed = threading.Condition(self._state_lock)
+        self._general_frames: deque[Frame] = deque()
+        self._pending_results: dict[str, ToolResultFrame] = {}
+        self._closed_error: Exception | None = None
+        self._reader_thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader_thread.start()
+
+    def send(self, frame: Frame) -> None:
+        payload = encode(frame)
+        with self._write_lock:
+            self._writer.write(payload)
+            self._writer.flush()
+
+    def recv(self) -> Frame:
+        with self._state_changed:
+            while not self._general_frames and self._closed_error is None:
+                self._state_changed.wait()
+            if self._general_frames:
+                return self._general_frames.popleft()
+            raise self._closed_error or ProtocolError("control pipe closed by host")
+
+    def call(self, name: str, args: dict[str, Any], timeout: float | None = None) -> Any:
+        call_id = uuid.uuid4().hex
+        self.send(ToolCallFrame(id=call_id, name=name, args=args, timeout=timeout))
+        with self._state_changed:
+            while call_id not in self._pending_results and self._closed_error is None:
+                self._state_changed.wait()
+            frame = self._pending_results.pop(call_id, None)
+            if frame is None:
+                raise self._closed_error or ProtocolError("control pipe closed by host")
+            if frame.ok:
+                return frame.value
+            err = frame.error
+            if err is None:
+                raise ToolError("Error", "tool call failed without error payload")
+            raise ToolError(err.type, err.message, err.trace)
+
+    def _read_loop(self) -> None:
+        try:
+            while True:
+                line = self._reader.readline()
+                if not line:
+                    raise ProtocolError("control pipe closed by host")
+                frame = decode(line)
+                with self._state_changed:
+                    if isinstance(frame, ToolResultFrame):
+                        self._pending_results[frame.id] = frame
+                    else:
+                        self._general_frames.append(frame)
+                    self._state_changed.notify_all()
+        except Exception as exc:
+            with self._state_changed:
+                self._closed_error = exc
+                self._state_changed.notify_all()
+
+
+_CLIENT: RpcClient | None = None
+
+
+def install(client: RpcClient) -> None:
+    """Set the process-wide RPC client. Called by ``_entry`` at boot."""
+    global _CLIENT
+    _CLIENT = client
+
+
+def get() -> RpcClient:
+    if _CLIENT is None:
+        raise RuntimeError("RPC client not installed; sandbox is not in a valid state")
+    return _CLIENT
+
+
+def call(name: str, args: dict[str, Any], timeout: float | None = None) -> Any:
+    """Convenience: invoke a tool through the installed client."""
+    return get().call(name, args, timeout)
+
+
+__all__ = ["RpcClient", "ToolError", "call", "get", "install"]

adk_code_mode_sandbox-0.1.0/src/adk_code_mode_sandbox/protocol.py

@@ -0,0 +1,193 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""JSON-lines wire protocol between the host and the sandbox.
+
+This module is the shared kernel: a byte-identical copy lives in the
+``adk_code_mode_sandbox`` wheel. A CI check enforces the two files are
+identical on every release.
+
+Design rules:
+
+- Zero dependencies outside the Python standard library. The sandbox wheel
+  must remain stdlib-only so the container image does not pull ADK / google-genai.
+- Frames are JSON objects, one per newline-terminated UTF-8 line.
+- Every frame carries a ``kind`` discriminator. Correlated pairs (e.g.
+  ``tool_call`` / ``tool_result``) carry a string ``id``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+PROTOCOL_VERSION = 1
+
+
+FrameKind = Literal[
+    "ready",
+    "run",
+    "tool_call",
+    "tool_result",
+    "log",
+    "done",
+    "shutdown",
+]
+
+
+@dataclass(frozen=True)
+class ReadyFrame:
+    """Sandbox → host. Sent once after boot."""
+
+    kind: Literal["ready"] = "ready"
+    protocol_version: int = PROTOCOL_VERSION
+
+
+@dataclass(frozen=True)
+class RunFrame:
+    """Host → sandbox. Instructs the sandbox to execute the given code."""
+
+    code: str = ""
+    kind: Literal["run"] = "run"
+
+
+@dataclass(frozen=True)
+class ToolCallFrame:
+    """Sandbox → host. Request to invoke a host-side tool."""
+
+    id: str = ""
+    name: str = ""
+    args: dict[str, Any] = field(default_factory=dict)
+    timeout: float | None = None
+    kind: Literal["tool_call"] = "tool_call"
+
+
+@dataclass(frozen=True)
+class ToolErrorPayload:
+    """The structured error body inside a failing ``tool_result`` frame."""
+
+    type: str
+    message: str
+    trace: str | None = None
+
+
+@dataclass(frozen=True)
+class ToolResultFrame:
+    """Host → sandbox. Result for a previously issued ``tool_call``."""
+
+    id: str = ""
+    ok: bool = True
+    value: Any = None
+    error: ToolErrorPayload | None = None
+    kind: Literal["tool_result"] = "tool_result"
+
+
+@dataclass(frozen=True)
+class LogFrame:
+    """Sandbox → host. Optional structured log line."""
+
+    level: str = "info"
+    msg: str = ""
+    kind: Literal["log"] = "log"
+
+
+@dataclass(frozen=True)
+class DoneFrame:
+    """Sandbox → host. User code finished. Host drains stdout/stderr next."""
+
+    exit_code: int = 0
+    kind: Literal["done"] = "done"
+
+
+@dataclass(frozen=True)
+class ShutdownFrame:
+    """Host → sandbox. Graceful shutdown."""
+
+    kind: Literal["shutdown"] = "shutdown"
+
+
+Frame = (
+    ReadyFrame | RunFrame | ToolCallFrame | ToolResultFrame | LogFrame | DoneFrame | ShutdownFrame
+)
+
+
+_KIND_TO_CLS: dict[str, type] = {
+    "ready": ReadyFrame,
+    "run": RunFrame,
+    "tool_call": ToolCallFrame,
+    "tool_result": ToolResultFrame,
+    "log": LogFrame,
+    "done": DoneFrame,
+    "shutdown": ShutdownFrame,
+}
+
+
+class ProtocolError(Exception):
+    """Raised when a frame cannot be decoded or is semantically invalid."""
+
+
+def encode(frame: Frame) -> bytes:
+    """Serialise a frame to a newline-terminated UTF-8 byte string."""
+    payload = asdict(frame)
+    return (json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def decode(line: bytes | str) -> Frame:
+    """Deserialise a single frame line.
+
+    Accepts either bytes or str; lines may or may not have a trailing newline.
+    """
+    if isinstance(line, (bytes, bytearray)):
+        text = line.decode("utf-8")
+    else:
+        text = line
+    text = text.rstrip("\r\n")
+    if not text:
+        raise ProtocolError("empty frame")
+    try:
+        obj = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"invalid JSON: {exc}") from exc
+    if not isinstance(obj, dict):
+        raise ProtocolError(f"frame must be a JSON object, got {type(obj).__name__}")
+    kind = obj.get("kind")
+    if not isinstance(kind, str):
+        raise ProtocolError("frame missing string `kind`")
+    cls = _KIND_TO_CLS.get(kind)
+    if cls is None:
+        raise ProtocolError(f"unknown frame kind: {kind!r}")
+    if cls is ToolResultFrame and obj.get("error") is not None:
+        err = obj["error"]
+        if not isinstance(err, dict):
+            raise ProtocolError("tool_result.error must be an object")
+        obj = dict(obj)
+        obj["error"] = ToolErrorPayload(
+            type=str(err.get("type", "Error")),
+            message=str(err.get("message", "")),
+            trace=err.get("trace"),
+        )
+    valid_fields = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+    filtered = {k: v for k, v in obj.items() if k in valid_fields}
+    try:
+        return cls(**filtered)  # type: ignore[no-any-return]
+    except TypeError as exc:
+        raise ProtocolError(f"invalid frame body for kind {kind!r}: {exc}") from exc
+
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "FrameKind",
+    "Frame",
+    "ReadyFrame",
+    "RunFrame",
+    "ToolCallFrame",
+    "ToolResultFrame",
+    "ToolErrorPayload",
+    "LogFrame",
+    "DoneFrame",
+    "ShutdownFrame",
+    "ProtocolError",
+    "encode",
+    "decode",
+]