lizard-adk 0.1.0__tar.gz

lizard_adk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.env
+.env.*
+!.env.example
+.venv*/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+node_modules/
+*.egg-info/
+*.eval
+logs/

lizard_adk-0.1.0/LICENSE

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Lizard
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

lizard_adk-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: lizard-adk
+Version: 0.1.0
+Summary: ADK tools and lifecycle hooks for Lizard Sandboxes.
+Project-URL: Homepage, https://lizard.build/sandboxes
+Project-URL: Repository, https://github.com/lizard-build/integrations
+Project-URL: Issues, https://github.com/lizard-build/integrations/issues
+Author: Lizard
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anyio<5,>=4
+Requires-Dist: google-adk<3,>=2.12.0
+Requires-Dist: lizard-sdk<0.2,>=0.1.60
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-socket>=0.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lizard-adk
+
+Lizard (lizard.build) connects ADK agents to Lizard Sandboxes. The plugin supplies four tools and releases each sandbox when its ADK invocation ends.
+
+## Install
+
+Requires Python 3.11+, ADK 2.12+, a Lizard project, and a project API key. The first PyPI release is pending. Install from source:
+
+```sh
+pip install 'lizard-adk @ git+https://github.com/lizard-build/integrations.git#subdirectory=packages/lizard-adk'
+```
+
+Set `LIZARD_API_KEY` and `LIZARD_PROJECT_ID`. The [agent example](examples/agent.py) also needs `GOOGLE_API_KEY` for Gemini.
+
+## Use
+
+```python
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+from lizard_adk import LizardPlugin
+
+plugin = LizardPlugin()
+root_agent = Agent(
+    name="sandbox_agent",
+    model="gemini-flash-latest",
+    tools=plugin.get_tools(),
+)
+runner = InMemoryRunner(
+    app=App(name="sandbox_example", root_agent=root_agent, plugins=[plugin]),
+    plugin_close_timeout=120,
+)
+# Run the agent, then always await runner.close() in a finally block.
+```
+
+Register the plugin in both places: `get_tools()` exposes the tools, and `App.plugins` runs cleanup. See [the complete example](examples/agent.py) for session creation, a prompt, and cleanup.
+
+| Tool | Result |
+| --- | --- |
+| `lizard_execute_command` | Shell stdout, stderr, and exit code |
+| `lizard_execute_code` | Python output, display results, and a structured error |
+| `lizard_read_file` | UTF-8 text, up to 1 MiB |
+| `lizard_write_file` | Write UTF-8 text, up to 1 MiB |
+
+Python variables and files persist across calls within one invocation. A later user message starts a new invocation and gets a fresh sandbox. The host keeps the Lizard API key; it does not put it in session state or tool results.
+
+## Options and limits
+
+Pass `project_id`, `api_key`, `api_url`, `size`, `lifetime_ms`, or `command_timeout_ms` to `LizardPlugin`. Defaults are the small interpreter template, a 15-minute lifetime, and a 60-second command timeout. The maximum command timeout is 120 seconds. The command tool defaults to `/home/user`.
+
+Shell output follows the Lizard SDK response limits. Use files for larger results. This plugin does not persist a sandbox between invocations or support custom Docker images. Always close the runner after errors or cancelled runs. If cleanup fails, retry `plugin.close()`; it retains the sandbox handle until deletion succeeds.
+
+## Checks
+
+Unit tests cover schemas, invocation isolation, files, errors, cancellation, and cleanup retries. Cloud tests exercise each tool and a real ADK runner with a scripted model, so they do not call a paid model API.
+
+```sh
+pip install -e '.[dev]'
+pytest tests -m 'not live' --disable-socket --allow-unix-socket
+# With Lizard credentials:
+LIZARD_LIVE_TESTS=1 pytest tests -m live
+```

lizard_adk-0.1.0/README.md

@@ -0,0 +1,62 @@
+# lizard-adk
+
+Lizard (lizard.build) connects ADK agents to Lizard Sandboxes. The plugin supplies four tools and releases each sandbox when its ADK invocation ends.
+
+## Install
+
+Requires Python 3.11+, ADK 2.12+, a Lizard project, and a project API key. The first PyPI release is pending. Install from source:
+
+```sh
+pip install 'lizard-adk @ git+https://github.com/lizard-build/integrations.git#subdirectory=packages/lizard-adk'
+```
+
+Set `LIZARD_API_KEY` and `LIZARD_PROJECT_ID`. The [agent example](examples/agent.py) also needs `GOOGLE_API_KEY` for Gemini.
+
+## Use
+
+```python
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+from lizard_adk import LizardPlugin
+
+plugin = LizardPlugin()
+root_agent = Agent(
+    name="sandbox_agent",
+    model="gemini-flash-latest",
+    tools=plugin.get_tools(),
+)
+runner = InMemoryRunner(
+    app=App(name="sandbox_example", root_agent=root_agent, plugins=[plugin]),
+    plugin_close_timeout=120,
+)
+# Run the agent, then always await runner.close() in a finally block.
+```
+
+Register the plugin in both places: `get_tools()` exposes the tools, and `App.plugins` runs cleanup. See [the complete example](examples/agent.py) for session creation, a prompt, and cleanup.
+
+| Tool | Result |
+| --- | --- |
+| `lizard_execute_command` | Shell stdout, stderr, and exit code |
+| `lizard_execute_code` | Python output, display results, and a structured error |
+| `lizard_read_file` | UTF-8 text, up to 1 MiB |
+| `lizard_write_file` | Write UTF-8 text, up to 1 MiB |
+
+Python variables and files persist across calls within one invocation. A later user message starts a new invocation and gets a fresh sandbox. The host keeps the Lizard API key; it does not put it in session state or tool results.
+
+## Options and limits
+
+Pass `project_id`, `api_key`, `api_url`, `size`, `lifetime_ms`, or `command_timeout_ms` to `LizardPlugin`. Defaults are the small interpreter template, a 15-minute lifetime, and a 60-second command timeout. The maximum command timeout is 120 seconds. The command tool defaults to `/home/user`.
+
+Shell output follows the Lizard SDK response limits. Use files for larger results. This plugin does not persist a sandbox between invocations or support custom Docker images. Always close the runner after errors or cancelled runs. If cleanup fails, retry `plugin.close()`; it retains the sandbox handle until deletion succeeds.
+
+## Checks
+
+Unit tests cover schemas, invocation isolation, files, errors, cancellation, and cleanup retries. Cloud tests exercise each tool and a real ADK runner with a scripted model, so they do not call a paid model API.
+
+```sh
+pip install -e '.[dev]'
+pytest tests -m 'not live' --disable-socket --allow-unix-socket
+# With Lizard credentials:
+LIZARD_LIVE_TESTS=1 pytest tests -m live
+```

lizard_adk-0.1.0/examples/agent.py

@@ -0,0 +1,46 @@
+"""Run with GOOGLE_API_KEY, LIZARD_API_KEY, and LIZARD_PROJECT_ID set."""
+
+import asyncio
+
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+from google.genai import types
+
+from lizard_adk import LizardPlugin
+
+
+async def main() -> None:
+    plugin = LizardPlugin()
+    root_agent = Agent(
+        model="gemini-flash-latest",
+        name="sandbox_agent",
+        instruction="Use the sandbox tools to run Python and check your answer.",
+        tools=plugin.get_tools(),
+    )
+    runner = InMemoryRunner(
+        app=App(name="sandbox_example", root_agent=root_agent, plugins=[plugin]),
+        plugin_close_timeout=120,
+    )
+    try:
+        session = await runner.session_service.create_session(
+            app_name="sandbox_example", user_id="example"
+        )
+        async for event in runner.run_async(
+            user_id="example",
+            session_id=session.id,
+            new_message=types.Content(
+                role="user",
+                parts=[types.Part.from_text(text="Use Python to sum the integers from 1 to 100.")],
+            ),
+        ):
+            if event.content:
+                for part in event.content.parts or []:
+                    if part.text:
+                        print(part.text)
+    finally:
+        await runner.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lizard_adk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lizard-adk"
+version = "0.1.0"
+description = "ADK tools and lifecycle hooks for Lizard Sandboxes."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{name = "Lizard"}]
+dependencies = ["lizard-sdk>=0.1.60,<0.2", "anyio>=4,<5", "google-adk>=2.12.0,<3"]
+
+[project.urls]
+Homepage = "https://lizard.build/sandboxes"
+Repository = "https://github.com/lizard-build/integrations"
+Issues = "https://github.com/lizard-build/integrations/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-socket>=0.7", "ruff>=0.9", "mypy>=1.14", "build", "twine"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lizard_adk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: creates temporary cloud resources; requires LIZARD_LIVE_TESTS=1"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.11"
+check_untyped_defs = true
+ignore_missing_imports = true

lizard_adk-0.1.0/src/lizard_adk/__init__.py

@@ -0,0 +1,5 @@
+"""Lizard Sandboxes tools and lifecycle management for ADK."""
+
+from .plugin import LizardPlugin
+
+__all__ = ["LizardPlugin"]

lizard_adk-0.1.0/src/lizard_adk/plugin.py

@@ -0,0 +1,180 @@
+"""One sandbox per ADK invocation, released when the invocation ends."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import anyio
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.tools import FunctionTool, ToolContext
+from lizard import CodeSandbox
+
+T = TypeVar("T")
+
+
+async def _blocking(fn: Callable[..., T], *args: Any, **kwargs: Any) -> T:
+    """Finish an SDK call before allowing cleanup to race with it."""
+    task = asyncio.create_task(asyncio.to_thread(fn, *args, **kwargs))
+    try:
+        return await asyncio.shield(task)
+    except asyncio.CancelledError:
+        with anyio.CancelScope(shield=True):
+            try:
+                await task
+            except Exception:
+                pass  # A failed SDK call must not replace the caller's cancellation.
+        raise
+
+
+class LizardPlugin(BasePlugin):
+    """Give an ADK invocation shell, code, and file tools in its own sandbox.
+
+    Register both ``plugin.get_tools()`` on the agent and ``plugins=[plugin]``
+    on the ADK App. Close the runner in a ``finally`` block. No sandbox or key
+    is stored in ADK session state or returned in a tool response.
+    """
+
+    def __init__(
+        self,
+        *,
+        project_id: str | None = None,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        size: str = "small",
+        lifetime_ms: int = 900_000,
+        command_timeout_ms: int = 60_000,
+    ) -> None:
+        super().__init__(name="lizard_sandboxes")
+        self._project = project_id or os.environ.get("LIZARD_PROJECT_ID")
+        if not self._project:
+            raise ValueError("Set LIZARD_PROJECT_ID or pass project_id.")
+        if size not in {"small", "medium", "large"}:
+            raise ValueError("size must be small, medium, or large.")
+        if lifetime_ms <= 0 or not 0 < command_timeout_ms <= 120_000:
+            raise ValueError("Use a positive lifetime and a command timeout of 1–120000 ms.")
+        self._options = dict(
+            project_id=self._project,
+            api_key=api_key,
+            api_url=api_url,
+            size=size,
+            timeout_ms=lifetime_ms,
+            metadata={"integration": "adk"},
+        )
+        self._command_timeout_ms = command_timeout_ms
+        self._sandboxes: dict[str, CodeSandbox] = {}
+        self._lock = asyncio.Lock()
+        self._closed = False
+
+    def get_tools(self) -> list[FunctionTool]:
+        """Return the four tools to pass to an ADK Agent."""
+        return [
+            FunctionTool(self.lizard_execute_command),
+            FunctionTool(self.lizard_execute_code),
+            FunctionTool(self.lizard_read_file),
+            FunctionTool(self.lizard_write_file),
+        ]
+
+    async def _sandbox(self, invocation_id: str) -> CodeSandbox:
+        async with self._lock:
+            if self._closed:
+                raise RuntimeError("The Lizard plugin is closed.")
+            if invocation_id not in self._sandboxes:
+                task = asyncio.create_task(asyncio.to_thread(CodeSandbox.create, **self._options))
+                try:
+                    sandbox = await asyncio.shield(task)
+                except asyncio.CancelledError:
+                    with anyio.CancelScope(shield=True):
+                        sandbox = await task
+                        self._sandboxes[invocation_id] = sandbox
+                        await _blocking(sandbox.kill)
+                        del self._sandboxes[invocation_id]
+                    raise
+                self._sandboxes[invocation_id] = sandbox
+            return self._sandboxes[invocation_id]
+
+    async def lizard_execute_command(
+        self, command: str, tool_context: ToolContext, cwd: str = "/home/user"
+    ) -> dict[str, Any]:
+        """Run a shell command in this invocation's sandbox.
+
+        Args:
+            command: Shell command to run in the sandbox.
+            cwd: Absolute working directory inside the sandbox.
+        """
+        sandbox = await self._sandbox(tool_context.invocation_id)
+        result = await _blocking(
+            sandbox.process.exec_, command, workdir=cwd, timeout_ms=self._command_timeout_ms
+        )
+        return {"stdout": result.stdout, "stderr": result.stderr, "exit_code": result.exit_code}
+
+    async def lizard_execute_code(self, code: str, tool_context: ToolContext) -> dict[str, Any]:
+        """Run Python code; variables persist within this invocation.
+
+        Args:
+            code: Python source code to run in the sandbox's Jupyter kernel.
+        """
+        sandbox = await self._sandbox(tool_context.invocation_id)
+        result = await _blocking(sandbox.run_code, code, timeout_ms=self._command_timeout_ms)
+        return {
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "results": [{"mime": item.mime, "data": item.data} for item in result.results],
+            "error": (
+                {"name": result.error.name, "message": result.error.message}
+                if result.error
+                else None
+            ),
+        }
+
+    async def lizard_read_file(self, path: str, tool_context: ToolContext) -> dict[str, Any]:
+        """Read a UTF-8 file of at most 1 MiB from the sandbox.
+
+        Args:
+            path: Absolute file path inside the sandbox.
+        """
+        sandbox = await self._sandbox(tool_context.invocation_id)
+        data = await _blocking(sandbox.fs.read_bytes, path)
+        if len(data) > 1_048_576:
+            raise ValueError("File exceeds 1 MiB; use a command to read a smaller part.")
+        return {"content": data.decode("utf-8")}
+
+    async def lizard_write_file(
+        self, path: str, content: str, tool_context: ToolContext
+    ) -> dict[str, Any]:
+        """Write a UTF-8 file, creating its parent directories if needed.
+
+        Args:
+            path: Absolute file path inside the sandbox.
+            content: Text to write. Replaces an existing file.
+        """
+        if len(content.encode("utf-8")) > 1_048_576:
+            raise ValueError("Content exceeds the 1 MiB tool limit.")
+        sandbox = await self._sandbox(tool_context.invocation_id)
+        await _blocking(sandbox.fs.write, path, content)
+        return {"path": path, "written": True}
+
+    async def after_run_callback(self, *, invocation_context: InvocationContext) -> None:
+        """Release this invocation's sandbox after the runner finishes it."""
+        async with self._lock:
+            key = invocation_context.invocation_id
+            if key in self._sandboxes:
+                await _blocking(self._sandboxes[key].kill)
+                del self._sandboxes[key]
+
+    async def close(self) -> None:
+        """Release remaining sandboxes, including those from failed invocations."""
+        async with self._lock:
+            self._closed = True
+            failures = []
+            for key, sandbox in list(self._sandboxes.items()):
+                try:
+                    await _blocking(sandbox.kill)
+                    del self._sandboxes[key]
+                except Exception as exc:
+                    failures.append(exc)
+            if failures:
+                raise ExceptionGroup("Sandbox cleanup failed; close() can be retried", failures)

lizard_adk-0.1.0/src/lizard_adk/py.typed

@@ -0,0 +1 @@
+

lizard_adk-0.1.0/tests/test_live.py

@@ -0,0 +1,83 @@
+import os
+from types import SimpleNamespace
+
+import pytest
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.models.base_llm import BaseLlm
+from google.adk.models.llm_response import LlmResponse
+from google.adk.runners import InMemoryRunner
+from google.genai import types
+
+from lizard_adk import LizardPlugin
+
+pytestmark = [
+    pytest.mark.live,
+    pytest.mark.skipif(os.getenv("LIZARD_LIVE_TESTS") != "1", reason="Set LIZARD_LIVE_TESTS=1"),
+]
+
+
+async def test_tools_live():
+    plugin = LizardPlugin()
+    context = SimpleNamespace(invocation_id="live-tools")
+    try:
+        assert (await plugin.lizard_execute_command("printf hello", context))["stdout"] == "hello"
+        await plugin.lizard_write_file("/tmp/adk.txt", "a\r\nb", context)
+        assert (await plugin.lizard_read_file("/tmp/adk.txt", context))["content"] == "a\r\nb"
+        await plugin.lizard_execute_code("answer = 21", context)
+        result = await plugin.lizard_execute_code("print(answer * 2)", context)
+        assert result["stdout"] == "42\n"
+        error = await plugin.lizard_execute_code("raise ValueError('expected')", context)
+        assert error["error"]["name"] == "ValueError"
+        await plugin.after_run_callback(invocation_context=context)
+        assert not plugin._sandboxes
+    finally:
+        await plugin.close()
+
+
+class ScriptedModel(BaseLlm):
+    model: str = "scripted-test"
+    calls: int = 0
+
+    async def generate_content_async(self, llm_request, stream=False):
+        self.calls += 1
+        part = (
+            types.Part.from_function_call(name="lizard_execute_code", args={"code": "print(6 * 7)"})
+            if self.calls == 1
+            else types.Part.from_text(text="done")
+        )
+        yield LlmResponse(content=types.Content(role="model", parts=[part]))
+
+
+async def test_real_runner_calls_tool_and_cleans_up():
+    plugin = LizardPlugin()
+    model = ScriptedModel()
+    agent = Agent(name="sandbox_agent", model=model, tools=plugin.get_tools())
+    runner = InMemoryRunner(
+        app=App(name="lizard_test", root_agent=agent, plugins=[plugin]), plugin_close_timeout=120
+    )
+    try:
+        session = await runner.session_service.create_session(
+            app_name="lizard_test", user_id="test"
+        )
+        events = [
+            event
+            async for event in runner.run_async(
+                user_id="test",
+                session_id=session.id,
+                new_message=types.Content(
+                    role="user", parts=[types.Part.from_text(text="Run Python")]
+                ),
+            )
+        ]
+        responses = [
+            part.function_response
+            for event in events
+            if event.content
+            for part in event.content.parts or []
+            if part.function_response
+        ]
+        assert any(response.response.get("stdout") == "42\n" for response in responses)
+        assert not plugin._sandboxes
+    finally:
+        await runner.close()

lizard_adk-0.1.0/tests/test_plugin.py

@@ -0,0 +1,159 @@
+import asyncio
+import threading
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from google.adk.agents import Agent
+from lizard.code_interpreter.types import Execution, ExecutionError, ResultItem
+
+from lizard_adk import LizardPlugin
+
+
+@pytest.fixture
+def native():
+    sandbox = MagicMock()
+    sandbox.process.exec_.return_value = SimpleNamespace(stdout="out", stderr="err", exit_code=3)
+    sandbox.run_code.return_value = Execution(stdout="42\n", results=[ResultItem(data="42")])
+    sandbox.fs.read_bytes.return_value = b"a\r\nb\x00"
+    with patch("lizard_adk.plugin.CodeSandbox.create", return_value=sandbox) as create:
+        yield sandbox, create
+
+
+def ctx(value="run-1"):
+    return SimpleNamespace(invocation_id=value)
+
+
+def test_config_requires_project(monkeypatch):
+    monkeypatch.delenv("LIZARD_PROJECT_ID", raising=False)
+    with pytest.raises(ValueError, match="LIZARD_PROJECT_ID"):
+        LizardPlugin()
+
+
+@pytest.mark.parametrize(
+    "options", [{"size": "huge"}, {"lifetime_ms": 0}, {"command_timeout_ms": 0}]
+)
+def test_invalid_config(options):
+    with pytest.raises(ValueError):
+        LizardPlugin(project_id="project", **options)
+
+
+def test_adk_tool_schemas_hide_context():
+    plugin = LizardPlugin(project_id="project")
+    tools = plugin.get_tools()
+    agent = Agent(name="test_agent", model="gemini-flash-latest", tools=tools)
+    assert len(agent.tools) == 4
+    for tool in tools:
+        declaration = tool._get_declaration()
+        schema = declaration.parameters_json_schema or declaration.parameters.model_dump()
+        assert "tool_context" not in schema["properties"]
+        assert schema["properties"]
+
+
+async def test_tools_share_invocation_and_forward_results(native):
+    sandbox, create = native
+    plugin = LizardPlugin(project_id="project")
+    result = await plugin.lizard_execute_command("false", ctx(), cwd="/tmp")
+    assert result == {"stdout": "out", "stderr": "err", "exit_code": 3}
+    sandbox.process.exec_.assert_called_once_with("false", workdir="/tmp", timeout_ms=60_000)
+    result = await plugin.lizard_execute_code("21 * 2", ctx())
+    assert result["results"] == [{"mime": "text/plain", "data": "42"}]
+    assert create.call_count == 1
+    await plugin.after_run_callback(invocation_context=ctx())
+    sandbox.kill.assert_called_once()
+    await plugin.close()
+    assert sandbox.kill.call_count == 1
+
+
+async def test_parallel_tools_create_once(native):
+    _, create = native
+    plugin = LizardPlugin(project_id="project")
+    await asyncio.gather(*(plugin.lizard_execute_code("42", ctx()) for _ in range(4)))
+    assert create.call_count == 1
+    await plugin.close()
+
+
+async def test_distinct_invocations_do_not_share_sandbox(native):
+    _, create = native
+    plugin = LizardPlugin(project_id="project")
+    await plugin.lizard_execute_code("42", ctx("a"))
+    await plugin.lizard_execute_code("42", ctx("b"))
+    assert create.call_count == 2
+    await plugin.close()
+
+
+async def test_python_error_is_structured(native):
+    native[0].run_code.return_value = Execution(error=ExecutionError("ValueError", "bad", "trace"))
+    plugin = LizardPlugin(project_id="project")
+    result = await plugin.lizard_execute_code("raise ValueError('bad')", ctx())
+    assert result["error"] == {"name": "ValueError", "message": "bad"}
+    await plugin.close()
+
+
+async def test_files_preserve_text_and_reject_large_output(native):
+    sandbox, _ = native
+    plugin = LizardPlugin(project_id="project")
+    assert (await plugin.lizard_read_file("/tmp/a", ctx()))["content"] == "a\r\nb\x00"
+    await plugin.lizard_write_file("/tmp/a", "new", ctx())
+    sandbox.fs.write.assert_called_with("/tmp/a", "new")
+    sandbox.fs.read_bytes.return_value = b"x" * 1_048_577
+    with pytest.raises(ValueError, match="1 MiB"):
+        await plugin.lizard_read_file("/tmp/a", ctx())
+    with pytest.raises(ValueError, match="1 MiB"):
+        await plugin.lizard_write_file("/tmp/a", "x" * 1_048_577, ctx())
+    await plugin.close()
+
+
+async def test_failed_cleanup_can_retry(native):
+    sandbox, _ = native
+    plugin = LizardPlugin(project_id="project")
+    await plugin.lizard_execute_code("42", ctx())
+    sandbox.kill.side_effect = [RuntimeError("network"), None]
+    with pytest.raises(ExceptionGroup):
+        await plugin.close()
+    await plugin.close()
+    assert sandbox.kill.call_count == 2
+    with pytest.raises(RuntimeError, match="closed"):
+        await plugin.lizard_execute_code("42", ctx())
+
+
+async def test_cancelled_creation_releases_resource(native):
+    sandbox, create = native
+    started, release = threading.Event(), threading.Event()
+
+    def slow_create(**kwargs):
+        started.set()
+        release.wait(5)
+        return sandbox
+
+    create.side_effect = slow_create
+    plugin = LizardPlugin(project_id="project")
+    task = asyncio.create_task(plugin.lizard_execute_code("42", ctx()))
+    await asyncio.to_thread(started.wait, 5)
+    task.cancel()
+    release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    sandbox.kill.assert_called_once()
+    await plugin.close()
+
+
+async def test_cancelled_sdk_call_preserves_cancellation_after_error():
+    import threading
+
+    from lizard_adk.plugin import _blocking
+
+    started = threading.Event()
+    release = threading.Event()
+
+    def delayed_error():
+        started.set()
+        release.wait(3)
+        raise RuntimeError("transport failed")
+
+    task = asyncio.create_task(_blocking(delayed_error))
+    await asyncio.to_thread(started.wait, 3)
+    task.cancel()
+    release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await task