adk-code-mode 2.0.0__tar.gz → 2.1.0__tar.gz

{adk_code_mode-2.0.0 → adk_code_mode-2.1.0}/.github/workflows/release-please.yml

@@ -112,5 +112,5 @@ jobs:
           file: docker/Dockerfile
           push: true
           tags: |
-            ghcr.io/a2anet/adk-code-mode:${{ needs.release-please.outputs.version }}
-            ghcr.io/a2anet/adk-code-mode:latest
+            ghcr.io/buildagenta/adk-code-mode:${{ needs.release-please.outputs.version }}
+            ghcr.io/buildagenta/adk-code-mode:latest

adk_code_mode-2.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "2.1.0"
+}

adk_code_mode-2.1.0/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+## [2.1.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v2.0.1...adk-code-mode-v2.1.0) (2026-11-08)
+
+
+### Features
+
+* show return types in the catalog and point the names tier at stubs ([#29](https://github.com/buildagenta/adk-code-mode/issues/29)) ([a238bfd](https://github.com/buildagenta/adk-code-mode/commit/a238bfd0eecf0acf371fe879a529a85a9e1f2dba))
+* type stub return values and escape docstrings ([#28](https://github.com/buildagenta/adk-code-mode/issues/28)) ([dcb15ab](https://github.com/buildagenta/adk-code-mode/commit/dcb15abfcecc841dc06f5051f41251a1f6ab9100))
+
+## [2.0.1](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v2.0.0...adk-code-mode-v2.0.1) (2026-11-02)
+
+
+### Miscellaneous Chores
+
+* credit Agenta as the author ([#25](https://github.com/buildagenta/adk-code-mode/issues/25)) ([bfe577e](https://github.com/buildagenta/adk-code-mode/commit/bfe577e9aaba31ed9d8f6423485b061deb77b963))
+
+## [2.0.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.6.1...adk-code-mode-v2.0.0) (2026-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* sandbox code that checked a tool result for an `error` key now gets an exception instead, and the sandbox image must be rebuilt for protocol version 3.
+
+### Features
+
+* raise when a tool call fails instead of returning the error ([#22](https://github.com/buildagenta/adk-code-mode/issues/22)) ([489083d](https://github.com/buildagenta/adk-code-mode/commit/489083d988cd7e958e94f3ef6acba6443284abd8))
+* stop a timed-out block without losing the turn's state ([#23](https://github.com/buildagenta/adk-code-mode/issues/23)) ([4720156](https://github.com/buildagenta/adk-code-mode/commit/47201568d0bb06527e32f850b7abb1b465e36920))
+
+## [1.6.1](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.6.0...adk-code-mode-v1.6.1) (2026-09-22)
+
+
+### Bug Fixes
+
+* exit the sandbox when the host disconnects mid-block ([bd3fb0f](https://github.com/buildagenta/adk-code-mode/commit/bd3fb0fb0d8a0cab9370f2ad6db56dfacf566cb4))
+
+## [1.6.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.5.0...adk-code-mode-v1.6.0) (2026-08-29)
+
+
+### Features
+
+* bound an execute_code block by default ([1609c0d](https://github.com/buildagenta/adk-code-mode/commit/1609c0d24b8563cba51434cd1214b4299aeefc86))
+* expand object oneOf/anyOf branches in tool stub docstrings ([#20](https://github.com/buildagenta/adk-code-mode/issues/20)) ([7d42cb1](https://github.com/buildagenta/adk-code-mode/commit/7d42cb1ee9d9e217d008776dc74a84034f4b67a9))
+
+## [1.5.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.4.0...adk-code-mode-v1.5.0) (2026-08-10)
+
+
+### Features
+
+* scope tool-name uniqueness to each namespace ([#17](https://github.com/buildagenta/adk-code-mode/issues/17)) ([437bc0d](https://github.com/buildagenta/adk-code-mode/commit/437bc0dc930521a933e5c25b4bd6103e9434fc27))
+
+## [1.4.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.3.0...adk-code-mode-v1.4.0) (2026-07-28)
+
+
+### Features
+
+* surface nested schema properties and validation keywords in tool stubs ([608d14b](https://github.com/buildagenta/adk-code-mode/commit/608d14bb115159b2991c7d8d4e3c641977fd0d66))
+
+
+### Documentation
+
+* document stub schema fidelity and the `JSON_SCHEMA_FOR_FUNC_DECL` flag in `README.md` ([219f02b](https://github.com/buildagenta/adk-code-mode/commit/219f02bd493c2e2d7275a0034ef2a40db933859f))
+
+## [1.3.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.2.0...adk-code-mode-v1.3.0) (2026-07-23)
+
+
+### Features
+
+* describe the sandbox to the model in a tagged `<code-mode>` block ([#14](https://github.com/buildagenta/adk-code-mode/issues/14)) ([662a281](https://github.com/buildagenta/adk-code-mode/commit/662a28138e8632b434e5f1ecd52793f7d83ee097))
+
+## [1.2.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.1.0...adk-code-mode-v1.2.0) (2026-07-23)
+
+
+### Features
+
+* add `custom_metadata` to the `save_artifact` tool ([dfd9a59](https://github.com/buildagenta/adk-code-mode/commit/dfd9a59bf1718084a1d5c02cc1ea453269223f16))
+
+## [1.1.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v1.0.0...adk-code-mode-v1.1.0) (2026-07-15)
+
+
+### Features
+
+* expose `tools` and `backend` as public properties on `ExecuteCodeTool` ([acfb704](https://github.com/buildagenta/adk-code-mode/commit/acfb704d388da5d66e318775e03fe055467679c2))
+
+## [1.0.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.4.1...adk-code-mode-v1.0.0) (2026-07-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* `CodeModeCodeExecutor`, `code_mode_before_model_callback`, and `CODE_MODE_SYSTEM_INSTRUCTION` no longer exist. Add `ExecuteCodeTool` to the agent's `tools=[...]` instead of wiring `code_executor=`; drop `before_model_callback=`, `generate_content_config=`, and `CODE_MODE_SYSTEM_INSTRUCTION` entirely; `release_invocation` is now `async`. See the README's migration section.
+
+### Features
+
+* replace `CodeModeCodeExecutor` with `ExecuteCodeTool` ([#10](https://github.com/buildagenta/adk-code-mode/issues/10)) ([b78572e](https://github.com/buildagenta/adk-code-mode/commit/b78572e72446930548760756255390d1a3cc388a))
+
+## [0.4.1](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.4.0...adk-code-mode-v0.4.1) (2026-07-10)
+
+
+### Documentation
+
+* note the sandbox writes to `/tools` in remote deployment guide ([96bb45e](https://github.com/buildagenta/adk-code-mode/commit/96bb45e4e18d9d54709f4c10b6b09cf3567ee385))
+
+## [0.4.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.3.0...adk-code-mode-v0.4.0) (2026-07-09)
+
+
+### Features
+
+* save tool results as artifacts with optional model-supplied naming ([76a3671](https://github.com/buildagenta/adk-code-mode/commit/76a36713b2c52bd5b8dc51d3669226a47e7108e5))
+
+
+### Bug Fixes
+
+* align code-mode example with the `<code-mode>` catalog and fix fences ([4a0cc6d](https://github.com/buildagenta/adk-code-mode/commit/4a0cc6d0fc99d5425f6682cc489e76c9ddef7d46))
+* clarify code-mode tools are a Python library, not function tools ([48d1018](https://github.com/buildagenta/adk-code-mode/commit/48d1018152a2ed2a8e7361de6ce0f43b31b429ce))
+* nudge the model to call tools via Python in the code-mode block ([141baf3](https://github.com/buildagenta/adk-code-mode/commit/141baf3a44976e82cf437b2064666be893d6d409))
+* update `CODE_MODE_SYSTEM_INSTRUCTION` and `README.md` ([933d42c](https://github.com/buildagenta/adk-code-mode/commit/933d42cb237b9d6deeb6611511cba28a0d5e9261))
+
+
+### Documentation
+
+* streamline `README.md` and fix broken code fences ([c237514](https://github.com/buildagenta/adk-code-mode/commit/c2375149df48e21318967090b6c85d0b1f411ea2))
+
+## [0.3.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.2.2...adk-code-mode-v0.3.0) (2026-07-06)
+
+
+### Features
+
+* hold one sandbox container open per turn (protocol v2) ([#6](https://github.com/buildagenta/adk-code-mode/issues/6)) ([aebe17d](https://github.com/buildagenta/adk-code-mode/commit/aebe17d2bbbf21cc0f05852efaf910ff6adc3154))
+
+
+### Documentation
+
+* lower startup probe period in `README.md` for faster cold starts ([e251af2](https://github.com/buildagenta/adk-code-mode/commit/e251af2cf7307c9944361e1a0e37c7191822a9e1))
+* note HTTP `/health` startup probe in `README.md` Cloud Run section ([d58fb10](https://github.com/buildagenta/adk-code-mode/commit/d58fb10f7aeda95e5c8cf29263a13e1333f661dd))
+
+## [0.2.2](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.2.1...adk-code-mode-v0.2.2) (2026-05-08)
+
+
+### Bug Fixes
+
+* use `python` fences instead of `tool_code` in `CodeModeCodeExecutor` ([efcc11e](https://github.com/buildagenta/adk-code-mode/commit/efcc11e1020c7544223074e00a8649f9c85d4ad6))
+
+## [0.2.1](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.2.0...adk-code-mode-v0.2.1) (2026-05-05)
+
+
+### Bug Fixes
+
+* rename `<tools>` tag to `<code-mode>` and update `CODE_MODE_SYSTEM_INSTRUCTION` ([0a06bfb](https://github.com/buildagenta/adk-code-mode/commit/0a06bfbdf22db6e0226e477d0ed074a6cc4d1515))
+
+
+### Documentation
+
+* update `README.md` with deployment instructions ([1dd7a95](https://github.com/buildagenta/adk-code-mode/commit/1dd7a95197fd56231ba97182526a825baf18508a))
+
+## [0.2.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v0.1.0...adk-code-mode-v0.2.0) (2026-05-03)
+
+
+### Features
+
+* add `RemoteBackend`, sandbox hardening, and make `README.md` more concise ([a1a70ee](https://github.com/buildagenta/adk-code-mode/commit/a1a70eec0686f164ce3796ba1d82bb82b7fbda59))
+
+
+### Bug Fixes
+
+* improve `CODE_MODE_SYSTEM_INSTRUCTION` ([0d00863](https://github.com/buildagenta/adk-code-mode/commit/0d008636e2e273b438192f737e20e207c165a610))
+
+## 0.1.0 (2026-04-29)
+
+
+### Features
+
+* ADK Code Mode: `CodeModeExecutor`, `DockerRuntime`, and more ([6ab1ac2](https://github.com/buildagenta/adk-code-mode/commit/6ab1ac28236d21ecb740d8e920e08e4d9bd969c5))
+
+
+### Documentation
+
+* shorten ADK code executor comparison table headers ([28116cf](https://github.com/buildagenta/adk-code-mode/commit/28116cf9f40b3623c31782a55885fa5c4f8c6bbf))

adk_code_mode-2.0.0/README.md → adk_code_mode-2.1.0/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: adk-code-mode
+Version: 2.1.0
+Summary: A "Code Mode" sandboxed code-execution tool for ADK agents to interact with tools, files, and custom packages with Python
+Project-URL: Documentation, https://github.com/buildagenta/adk-code-mode#readme
+Project-URL: Issues, https://github.com/buildagenta/adk-code-mode/issues
+Project-URL: Source, https://github.com/buildagenta/adk-code-mode
+Author-email: Agenta <hello@buildagenta.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: a2a,adk,agents,code-mode,execute-code
+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
+Requires-Dist: google-adk<2.0.0,>=1.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: websockets>=14.0
+Provides-Extra: docker
+Requires-Dist: docker>=7.0.0; extra == 'docker'
+Description-Content-Type: text/markdown
+
 # ADK Code Mode
 
 A [Code Mode](https://blog.cloudflare.com/code-mode/) sandboxed code-execution tool for [Agent Development Kit (ADK)](https://github.com/google/adk-python).
@@ -14,7 +41,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 - **Call ADK tools from sandbox code** — imports against the `tools` package proxy back to the host and run through ADK's `before_tool` / `after_tool` / `on_error` callbacks and the plugin manager exactly as direct tool calls would.
 - **Failed tool calls raise** — a REST tool whose API answers with an HTTP error raises `HTTPStatusError` (with `status_code` and `body`), and any other failure, including an MCP tool that reports one, raises `ToolError`. ADK returns these as values for a model to read, but sandbox code reads return values, so it would otherwise carry on as if the call had worked.
 - **Bake any Python package into the image** — extend the published base image with anything the model's code needs to `import`, no runtime `pip install` required. The sandbox reports what it has installed, so the model is told about it automatically.
-- **Cross-turn persistence via ADK Artifacts** — `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`. Files the code creates or changes are saved as artifacts automatically too.
+- **Cross-turn persistence via ADK Artifacts** — files the code creates or changes are saved as artifacts automatically, and `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
 - **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and large results stay out of the prompt. Opt out with `save_tool_results_as_artifacts=False`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
 - **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
@@ -98,7 +125,7 @@ override_feature_enabled(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, True)
 
 tool = ExecuteCodeTool(
     tools=[my_fn_tool, McpToolset(...), OpenAPIToolset(...)],
-    backend=UnsafeLocalDockerBackend(image="ghcr.io/a2anet/adk-code-mode:latest"),
+    backend=UnsafeLocalDockerBackend(image="ghcr.io/buildagenta/adk-code-mode:latest"),
 )
 ```
 
@@ -118,8 +145,8 @@ print(send_message(channel="C123", text="hi"))
 ```bash
 # Push the sandbox image to Artifact Registry
 gcloud auth configure-docker <region>-docker.pkg.dev
-docker pull --platform linux/amd64 ghcr.io/a2anet/adk-code-mode:latest
-docker tag  ghcr.io/a2anet/adk-code-mode:latest \
+docker pull --platform linux/amd64 ghcr.io/buildagenta/adk-code-mode:latest
+docker tag  ghcr.io/buildagenta/adk-code-mode:latest \
     <region>-docker.pkg.dev/<project>/<repository>/adk-code-mode-sandbox:latest
 docker push <region>-docker.pkg.dev/<project>/<repository>/adk-code-mode-sandbox:latest
 
@@ -225,9 +252,7 @@ save_artifact(
     mime_type="application/json",
 )
 print(list_artifacts())
-report = load_artifact(filename="report.json")
-if report is not None and report["kind"] == "text":
-    payload = json.loads(report["data"])
+report = json.loads(load_artifact(filename="report.json")["data"])
 ```
 
 Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`:
@@ -243,7 +268,7 @@ ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)
 
 ### Tool results as artifacts
 
-By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and keeps large results out of the model's context — a result whose serialised form exceeds the threshold is replaced in the reply with a short note pointing at the artifact, which the model reloads with `load_artifact`.
+By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. Results over 50,000 bytes return a dictionary with a `tool_result_artifact` filename and a `note` instead of the inline result.
 
 Naming is transparent: the filename is derived from the tool name and call id. Each wrapped tool also gains two **optional** parameters — `artifact_name` and `artifact_description` — that the model may pass to name/describe the saved artifact; both land in the artifact's `custom_metadata` (`code_mode.artifact_name` / `code_mode.artifact_description`) alongside the marker. Set `save_tool_results_as_artifacts=False` to return tool results inline without persisting them.
 
@@ -253,10 +278,10 @@ ExecuteCodeTool(tools=..., backend=..., save_tool_results_as_artifacts=True)
 
 ## 🐳 Sandbox Image
 
-The published base image (`ghcr.io/a2anet/adk-code-mode`) works as-is for tools whose execution is fully host-side. To bake in extra Python packages:
+The published base image (`ghcr.io/buildagenta/adk-code-mode`) works as-is for tools whose execution is fully host-side. To bake in extra Python packages:
 
 ```dockerfile
-FROM ghcr.io/a2anet/adk-code-mode:latest
+FROM ghcr.io/buildagenta/adk-code-mode:latest
 RUN pip install --no-cache-dir pandas==2.2.*
 ```
 
@@ -311,14 +336,18 @@ Two surfaces, deliberately kept apart. The **tool description** is the invariant
 Execute Python code in a sandboxed container. Custom tools are Python functions to
 import from the `tools` package (e.g. `from tools.slack import send_message`). See
 the `<code-mode>` section of the system instruction for the Python version,
-preinstalled packages, and available functions. Print anything you want to see; only
-stdout/stderr are returned. Variables and the working directory persist across calls
-within the same turn and reset on the next turn — use `save_artifact` /
-`load_artifact` (imported the same way) to persist across turns. Files created or
-changed by the code are saved as artifacts automatically
+preinstalled packages, and available functions. Print function calls, variables, etc.
+to see output, only stdout/stderr are returned. Variables and files persist across
+calls within the same turn and reset on the next turn. Every file the code writes in
+the working directory, and every tool's result, is saved as an artifact; use
+`load_artifact` (imported the same way) to read one in a later turn. Large tool
+results return a `tool_result_artifact` pointer. Tool calls that
+call APIs raise HTTP errors as `HTTPStatusError` (with `status_code` and `body`);
+other failures raise `ToolError`. Import both from `tools`. Each call can run for up
+to 60s.
 ~~~
 
-With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by `List /tools/ and read a file's docstring to see what's available.`, so the description never points at a section that wasn't appended.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result" and the sentence about large results, and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.
 
 The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
@@ -339,7 +368,15 @@ yaml: PyYAML 6.0.2
 
 from tools.slack import list_channels, send_message
 
-def list_channels() -> Any:
+class ListChannelsResponse(TypedDict):
+    channels: list[ChannelsItem]
+    next_cursor: NotRequired[str]
+
+class ChannelsItem(TypedDict):
+    id: str
+    name: str
+
+def list_channels() -> ListChannelsResponse:
     """List Slack channels."""
     ...
 
@@ -355,6 +392,8 @@ from tools import save_artifact, load_artifact, list_artifacts
 </code-mode>
 ~~~
 
+Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A saved tool result can also be a `ToolResultArtifact` pointer when it exceeds the size threshold. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.
+
 Tags are indented; their content is not. The `<tools-package>` body is Python source, where leading whitespace is meaningful. Each installed-package line is `<import name>: <distribution> <version>`; namespace imports supplied by multiple distributions list every provider in deterministic order. Import names and providers are sorted so the block stays byte-stable for prompt caching. `<python-version>` and `<installed-packages>` are omitted entirely — rather than rendered blank — when the sandbox hasn't reported yet or the image has no extra packages, since an empty tag reads as "none exist".
 
 With `save_tool_results_as_artifacts` enabled (the default), each non-artifact tool above — e.g. `list_channels` and `send_message` — also carries two optional `artifact_name: str | None = ...` / `artifact_description: str | None = ...` parameters for naming its saved result.
@@ -364,7 +403,10 @@ With `save_tool_results_as_artifacts` enabled (the default), each non-artifact t
 A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishing. The Python version and package list survive every tier — they're small, and the model cannot discover them any other way.
 
 1. **Full** — as above.
-2. **Names only** — signatures and docstrings dropped, import lines kept:
+2. **Names only** — types, signatures and docstrings dropped, import lines kept. `<how-to-use>` gains:
+
+   > Before calling a function you haven't used, print its stub to see its signature, docstring and the fields of its return type: `/tools/<module>/<fn>.py`, or `/tools/<fn>.py` for a function imported from `tools`. Print every stub you need in one `execute_code` call.
+
 
    ~~~
      <tools-package>
@@ -374,11 +416,11 @@ A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishi
      </tools-package>
    ~~~
 
-3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+3. **Pointer** — the catalog is replaced by a note, and this tier is emitted no matter how small the budget. `<how-to-use>` gains the same text, prefixed with "List `/tools/` and its module directories to find the functions available.":
 
    ~~~
      <tools-package>
-   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+   The full catalog is too large to include here.
      </tools-package>
    ~~~
 
@@ -386,11 +428,12 @@ At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib
-print(list(pathlib.Path("/tools").iterdir()))
-print(open("/tools/slack/send_message.py").read())  # signature + docstring
+print(sorted(pathlib.Path("/tools").rglob("*.py")))
+print(open("/tools/slack/send_message.py").read())  # types, signature + docstring
+print(open("/tools/slack/list_channels.py").read())
 ```
 
-Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns `{"kind": "text" | "bytes", "data": str, "mime_type": str | None}`.
+Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns a dictionary with `kind`, `data`, and `mime_type`. Text and JSON use `kind="text"` and keep the string in `data`. Binary artifacts use `kind="bytes"` and store base64 in `data`.
 
 ## 🛡️ Safety
 
@@ -423,7 +466,7 @@ Named "Unsafe" intentionally: it binds a TCP listener on `0.0.0.0`, communicates
 ## ⚠️ Limitations
 
 - **No credential-requesting tools.** Tools that need ADK to request credentials, confirmations, UI widgets, agent transfer, escalation, or that yield without an immediate response are rejected with a structured error.
-- **State is turn-scoped.** Variables and the working directory persist across `execute_code` calls **within** a turn, but reset between turns. Use `save_artifact` / `load_artifact` to persist across turns.
+- **State is turn-scoped.** Variables and the working directory persist across `execute_code` calls **within** a turn, but reset between turns. Files the code writes and tool results are saved as artifacts; use `load_artifact` to read them in a later turn.
 - **No runtime package installation.** The sandbox ships with the Python Standard Library and the runtime's own dependencies only. Extra packages must be baked into the image at build time.
 
 ## 🛠️ Development
@@ -443,9 +486,9 @@ uv run pytest -m docker
 
 `adk-code-mode` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.
 
-## 🤝 Join the A2A Net Community
+## 🤝 Join the Agenta 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!
+Agenta 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)
+- 🌍 Site: [Agenta](https://buildagenta.com)
 - 🤖 Discord: [Join the Discord](https://discord.gg/674NGXpAjU)

adk_code_mode-2.0.0/PKG-INFO → adk_code_mode-2.1.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.5
-Name: adk-code-mode
-Version: 2.0.0
-Summary: A "Code Mode" sandboxed code-execution tool for ADK agents to interact with tools, files, and custom packages with Python
-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
-License-File: LICENSE
-Keywords: a2a,adk,agents,code-mode,execute-code
-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
-Requires-Dist: google-adk<2.0.0,>=1.0.0
-Requires-Dist: google-genai>=1.0.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: websockets>=14.0
-Provides-Extra: docker
-Requires-Dist: docker>=7.0.0; extra == 'docker'
-Description-Content-Type: text/markdown
-
 # ADK Code Mode
 
 A [Code Mode](https://blog.cloudflare.com/code-mode/) sandboxed code-execution tool for [Agent Development Kit (ADK)](https://github.com/google/adk-python).
@@ -41,7 +14,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 - **Call ADK tools from sandbox code** — imports against the `tools` package proxy back to the host and run through ADK's `before_tool` / `after_tool` / `on_error` callbacks and the plugin manager exactly as direct tool calls would.
 - **Failed tool calls raise** — a REST tool whose API answers with an HTTP error raises `HTTPStatusError` (with `status_code` and `body`), and any other failure, including an MCP tool that reports one, raises `ToolError`. ADK returns these as values for a model to read, but sandbox code reads return values, so it would otherwise carry on as if the call had worked.
 - **Bake any Python package into the image** — extend the published base image with anything the model's code needs to `import`, no runtime `pip install` required. The sandbox reports what it has installed, so the model is told about it automatically.
-- **Cross-turn persistence via ADK Artifacts** — `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`. Files the code creates or changes are saved as artifacts automatically too.
+- **Cross-turn persistence via ADK Artifacts** — files the code creates or changes are saved as artifacts automatically, and `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
 - **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and large results stay out of the prompt. Opt out with `save_tool_results_as_artifacts=False`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
 - **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
@@ -125,7 +98,7 @@ override_feature_enabled(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, True)
 
 tool = ExecuteCodeTool(
     tools=[my_fn_tool, McpToolset(...), OpenAPIToolset(...)],
-    backend=UnsafeLocalDockerBackend(image="ghcr.io/a2anet/adk-code-mode:latest"),
+    backend=UnsafeLocalDockerBackend(image="ghcr.io/buildagenta/adk-code-mode:latest"),
 )
 ```
 
@@ -145,8 +118,8 @@ print(send_message(channel="C123", text="hi"))
 ```bash
 # Push the sandbox image to Artifact Registry
 gcloud auth configure-docker <region>-docker.pkg.dev
-docker pull --platform linux/amd64 ghcr.io/a2anet/adk-code-mode:latest
-docker tag  ghcr.io/a2anet/adk-code-mode:latest \
+docker pull --platform linux/amd64 ghcr.io/buildagenta/adk-code-mode:latest
+docker tag  ghcr.io/buildagenta/adk-code-mode:latest \
     <region>-docker.pkg.dev/<project>/<repository>/adk-code-mode-sandbox:latest
 docker push <region>-docker.pkg.dev/<project>/<repository>/adk-code-mode-sandbox:latest
 
@@ -252,9 +225,7 @@ save_artifact(
     mime_type="application/json",
 )
 print(list_artifacts())
-report = load_artifact(filename="report.json")
-if report is not None and report["kind"] == "text":
-    payload = json.loads(report["data"])
+report = json.loads(load_artifact(filename="report.json")["data"])
 ```
 
 Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`:
@@ -270,7 +241,7 @@ ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)
 
 ### Tool results as artifacts
 
-By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and keeps large results out of the model's context — a result whose serialised form exceeds the threshold is replaced in the reply with a short note pointing at the artifact, which the model reloads with `load_artifact`.
+By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. Results over 50,000 bytes return a dictionary with a `tool_result_artifact` filename and a `note` instead of the inline result.
 
 Naming is transparent: the filename is derived from the tool name and call id. Each wrapped tool also gains two **optional** parameters — `artifact_name` and `artifact_description` — that the model may pass to name/describe the saved artifact; both land in the artifact's `custom_metadata` (`code_mode.artifact_name` / `code_mode.artifact_description`) alongside the marker. Set `save_tool_results_as_artifacts=False` to return tool results inline without persisting them.
 
@@ -280,10 +251,10 @@ ExecuteCodeTool(tools=..., backend=..., save_tool_results_as_artifacts=True)
 
 ## 🐳 Sandbox Image
 
-The published base image (`ghcr.io/a2anet/adk-code-mode`) works as-is for tools whose execution is fully host-side. To bake in extra Python packages:
+The published base image (`ghcr.io/buildagenta/adk-code-mode`) works as-is for tools whose execution is fully host-side. To bake in extra Python packages:
 
 ```dockerfile
-FROM ghcr.io/a2anet/adk-code-mode:latest
+FROM ghcr.io/buildagenta/adk-code-mode:latest
 RUN pip install --no-cache-dir pandas==2.2.*
 ```
 
@@ -338,14 +309,18 @@ Two surfaces, deliberately kept apart. The **tool description** is the invariant
 Execute Python code in a sandboxed container. Custom tools are Python functions to
 import from the `tools` package (e.g. `from tools.slack import send_message`). See
 the `<code-mode>` section of the system instruction for the Python version,
-preinstalled packages, and available functions. Print anything you want to see; only
-stdout/stderr are returned. Variables and the working directory persist across calls
-within the same turn and reset on the next turn — use `save_artifact` /
-`load_artifact` (imported the same way) to persist across turns. Files created or
-changed by the code are saved as artifacts automatically
+preinstalled packages, and available functions. Print function calls, variables, etc.
+to see output, only stdout/stderr are returned. Variables and files persist across
+calls within the same turn and reset on the next turn. Every file the code writes in
+the working directory, and every tool's result, is saved as an artifact; use
+`load_artifact` (imported the same way) to read one in a later turn. Large tool
+results return a `tool_result_artifact` pointer. Tool calls that
+call APIs raise HTTP errors as `HTTPStatusError` (with `status_code` and `body`);
+other failures raise `ToolError`. Import both from `tools`. Each call can run for up
+to 60s.
 ~~~
 
-With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by `List /tools/ and read a file's docstring to see what's available.`, so the description never points at a section that wasn't appended.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result" and the sentence about large results, and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.
 
 The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
@@ -366,7 +341,15 @@ yaml: PyYAML 6.0.2
 
 from tools.slack import list_channels, send_message
 
-def list_channels() -> Any:
+class ListChannelsResponse(TypedDict):
+    channels: list[ChannelsItem]
+    next_cursor: NotRequired[str]
+
+class ChannelsItem(TypedDict):
+    id: str
+    name: str
+
+def list_channels() -> ListChannelsResponse:
     """List Slack channels."""
     ...
 
@@ -382,6 +365,8 @@ from tools import save_artifact, load_artifact, list_artifacts
 </code-mode>
 ~~~
 
+Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A saved tool result can also be a `ToolResultArtifact` pointer when it exceeds the size threshold. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.
+
 Tags are indented; their content is not. The `<tools-package>` body is Python source, where leading whitespace is meaningful. Each installed-package line is `<import name>: <distribution> <version>`; namespace imports supplied by multiple distributions list every provider in deterministic order. Import names and providers are sorted so the block stays byte-stable for prompt caching. `<python-version>` and `<installed-packages>` are omitted entirely — rather than rendered blank — when the sandbox hasn't reported yet or the image has no extra packages, since an empty tag reads as "none exist".
 
 With `save_tool_results_as_artifacts` enabled (the default), each non-artifact tool above — e.g. `list_channels` and `send_message` — also carries two optional `artifact_name: str | None = ...` / `artifact_description: str | None = ...` parameters for naming its saved result.
@@ -391,7 +376,10 @@ With `save_tool_results_as_artifacts` enabled (the default), each non-artifact t
 A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishing. The Python version and package list survive every tier — they're small, and the model cannot discover them any other way.
 
 1. **Full** — as above.
-2. **Names only** — signatures and docstrings dropped, import lines kept:
+2. **Names only** — types, signatures and docstrings dropped, import lines kept. `<how-to-use>` gains:
+
+   > Before calling a function you haven't used, print its stub to see its signature, docstring and the fields of its return type: `/tools/<module>/<fn>.py`, or `/tools/<fn>.py` for a function imported from `tools`. Print every stub you need in one `execute_code` call.
+
 
    ~~~
      <tools-package>
@@ -401,11 +389,11 @@ A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishi
      </tools-package>
    ~~~
 
-3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+3. **Pointer** — the catalog is replaced by a note, and this tier is emitted no matter how small the budget. `<how-to-use>` gains the same text, prefixed with "List `/tools/` and its module directories to find the functions available.":
 
    ~~~
      <tools-package>
-   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+   The full catalog is too large to include here.
      </tools-package>
    ~~~
 
@@ -413,11 +401,12 @@ At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib
-print(list(pathlib.Path("/tools").iterdir()))
-print(open("/tools/slack/send_message.py").read())  # signature + docstring
+print(sorted(pathlib.Path("/tools").rglob("*.py")))
+print(open("/tools/slack/send_message.py").read())  # types, signature + docstring
+print(open("/tools/slack/list_channels.py").read())
 ```
 
-Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns `{"kind": "text" | "bytes", "data": str, "mime_type": str | None}`.
+Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns a dictionary with `kind`, `data`, and `mime_type`. Text and JSON use `kind="text"` and keep the string in `data`. Binary artifacts use `kind="bytes"` and store base64 in `data`.
 
 ## 🛡️ Safety
 
@@ -450,7 +439,7 @@ Named "Unsafe" intentionally: it binds a TCP listener on `0.0.0.0`, communicates
 ## ⚠️ Limitations
 
 - **No credential-requesting tools.** Tools that need ADK to request credentials, confirmations, UI widgets, agent transfer, escalation, or that yield without an immediate response are rejected with a structured error.
-- **State is turn-scoped.** Variables and the working directory persist across `execute_code` calls **within** a turn, but reset between turns. Use `save_artifact` / `load_artifact` to persist across turns.
+- **State is turn-scoped.** Variables and the working directory persist across `execute_code` calls **within** a turn, but reset between turns. Files the code writes and tool results are saved as artifacts; use `load_artifact` to read them in a later turn.
 - **No runtime package installation.** The sandbox ships with the Python Standard Library and the runtime's own dependencies only. Extra packages must be baked into the image at build time.
 
 ## 🛠️ Development
@@ -470,9 +459,9 @@ uv run pytest -m docker
 
 `adk-code-mode` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.
 
-## 🤝 Join the A2A Net Community
+## 🤝 Join the Agenta 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!
+Agenta 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)
+- 🌍 Site: [Agenta](https://buildagenta.com)
 - 🤖 Discord: [Join the Discord](https://discord.gg/674NGXpAjU)

{adk_code_mode-2.0.0 → adk_code_mode-2.1.0}/docker/Dockerfile

@@ -1,6 +1,6 @@
 FROM python:3.13-slim
 
-LABEL org.opencontainers.image.source="https://github.com/a2anet/adk-code-mode"
+LABEL org.opencontainers.image.source="https://github.com/buildagenta/adk-code-mode"
 LABEL org.opencontainers.image.description="Sandbox base image for ADK Code Mode"
 LABEL org.opencontainers.image.licenses="Apache-2.0"