diff --git a/example/app/agent/SandboxDemo.cpp b/example/app/agent/SandboxDemo.cpp
index 9890b4a..5b724a2 100644
--- a/example/app/agent/SandboxDemo.cpp
+++ b/example/app/agent/SandboxDemo.cpp
@@ -9,6 +9,9 @@
#include "google/sandbox/caps.h"
#include "google/sandbox/code_executor.h"
#include "google/sandbox/computer_use.h"
+#include "google/sandbox/data_plane_connector.h"
+#include "google/sandbox/operations.h"
+#include "google/sandbox/stream_executor.h"
#include "google/sandbox/sandboxes.h"
#include "google/sandbox/shell_runner.h"
#include "google/sandbox/snapshots.h"
@@ -63,6 +66,20 @@ long number(const Fields& in, const char* key, long fallback) {
return std::stol(v);
}
+bool flag(const Fields& in, const char* key) { return field(in, key) == "true"; }
+
+// A JSON object given as text (params of a CDP command).
+Json object_of(const Fields& in, const char* key) {
+ std::string text = field(in, key);
+ if (text.empty()) return Json::object();
+ try {
+ Json doc = Json::parse(text);
+ if (doc.is_object()) return doc;
+ } catch (const clients::body::JsonError&) {
+ }
+ throw fw::HttpError(422, "validation_error", std::string(key) + " must be a JSON object");
+}
+
[[noreturn]] void rethrow(const google::GoogleError& e) {
if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED")
throw fw::HttpError(503, "google_not_configured", e.message());
@@ -164,6 +181,51 @@ OAuth token (GOOGLE_ACCESS_TOKEN); every call is capped.
+
+
+
+
+
+
{% endblock %}
@@ -181,7 +243,10 @@ void register_agent_sandbox_demo(fw::Router& router, Services& services) {
auto sandboxes = std::make_shared(client);
auto code = std::make_shared(client);
auto shell = std::make_shared(client);
- auto computer = std::make_shared(client);
+ auto connector = std::make_shared(client, sb::DataPlaneOptions::from_env());
+ auto computer = std::make_shared(client, connector);
+ auto operations = std::make_shared(client);
+ auto streamer = std::make_shared(client);
auto snapshots = std::make_shared(client);
auto templates = std::make_shared(client);
@@ -192,14 +257,16 @@ void register_agent_sandbox_demo(fw::Router& router, Services& services) {
"text/html; charset=utf-8");
});
- router.get("/agent/sandbox/status", "agent-sandbox-status", [client](fw::Request) {
+ router.get("/agent/sandbox/status", "agent-sandbox-status", [client, connector](fw::Request) {
Json o = Json::object();
o.set("configured", Json(client->configured()));
+ // The data plane signs JWTs with a service account: name only whether one is set.
+ o.set("data_plane_signer", Json(!connector->options().service_account_email.empty()));
o.set("caps", caps_json());
Json kinds = Json::array();
for (const char* k : {"code", "shell", "computer"}) kinds.push(Json(k));
o.set("kinds", kinds);
- o.set("api", Json("aiplatform v1 (computer use and templates: v1beta1)"));
+ o.set("api", Json("aiplatform v1 (computer use, templates, bidiExecute: v1beta1); data plane: JWT proxy and CDP WebSocket"));
fw::Response res = fw::JsonResponse(o.dump(), 200);
res.headers.set("Cache-Control", "no-store");
return res;
@@ -322,13 +389,150 @@ void register_agent_sandbox_demo(fw::Router& router, Services& services) {
else r = computer->screenshot(name);
Json o = Json::object();
o.set("result", r.result);
- o.set("exec", r.exec.to_json());
+ o.set("status", Json(r.status));
if (!r.screenshot_png.empty())
o.set("screenshot_png_b64", Json(security::crypto::Base64::encode(r.screenshot_png)));
return o;
});
});
+ router.post("/agent/sandbox/dataplane", "agent-sandbox-dataplane", [computer](fw::Request req) {
+ Fields in = fields_of(req);
+ std::string action = field(in, "action");
+ if (action != "health" && action != "tabs" && action != "new_tab" && action != "activate" &&
+ action != "close" && action != "command")
+ throw fw::HttpError(422, "validation_error",
+ "action must be health, tabs, new_tab, activate, close or command");
+ Json params = object_of(in, "params");
+ return guarded([&] {
+ std::string name = field(in, "name");
+ if (action == "health") return computer->health(name);
+ if (action == "tabs") return computer->list_tabs(name);
+ if (action == "new_tab") return computer->create_tab(name);
+ if (action == "activate") return computer->activate_tab(name, field(in, "tab_id"));
+ if (action == "close") return computer->close_tab(name, field(in, "tab_id"));
+ sb::ActionResult r = computer->command(name, field(in, "command"), params);
+ Json o = Json::object();
+ o.set("status", Json(r.status));
+ o.set("result", r.result);
+ return o;
+ });
+ });
+
+ // One WebSocket round trip: connect, optionally attach the first page, one
+ // CDP call, close. The session never outlives the request.
+ router.post("/agent/sandbox/cdp", "agent-sandbox-cdp", [computer](fw::Request req) {
+ Fields in = fields_of(req);
+ Json params = object_of(in, "params");
+ std::string method = field(in, "method");
+ return guarded([&] {
+ sb::DataPlane::validate_command(method);
+ std::unique_ptr cdp = computer->open_cdp(field(in, "name"));
+ std::string session;
+ if (field(in, "page") != "false") session = cdp->attach_first_page();
+ Json o = Json::object();
+ o.set("result", cdp->call(method, params, session));
+ Json events = Json::array();
+ for (const Json& e : cdp->take_events()) events.push(e);
+ o.set("events", events);
+ o.set("dropped_events", Json(static_cast(cdp->dropped_events())));
+ cdp->close();
+ return o;
+ });
+ });
+
+ router.post("/agent/sandbox/stream", "agent-sandbox-stream", [streamer](fw::Request req) {
+ Fields in = fields_of(req);
+ std::string mode = field(in, "mode").empty() ? "shell" : field(in, "mode");
+ if (mode != "shell" && mode != "code")
+ throw fw::HttpError(422, "validation_error", "mode must be shell or code");
+ return guarded([&] {
+ std::vector inputs =
+ mode == "shell" ? sb::ChunkCodec::shell_inputs(field(in, "input"), field(in, "cwd"),
+ static_cast(number(in, "timeout", sb::SandboxCaps::kDefaultShellTimeoutSeconds)))
+ : sb::ChunkCodec::code_inputs(field(in, "input"), {});
+ if (mode == "shell") sb::ShellRunner::validate({field(in, "input"), field(in, "cwd"),
+ static_cast(number(in, "timeout", sb::SandboxCaps::kDefaultShellTimeoutSeconds))},
+ sb::SandboxCaps::kMaxCommandBytes);
+ else sb::CodeExecutor::validate(field(in, "input"), {});
+ return streamer->run(field(in, "name"), inputs).to_json();
+ });
+ });
+
+ router.post("/agent/sandbox/operations", "agent-sandbox-operations", [operations](fw::Request req) {
+ Fields in = fields_of(req);
+ std::string op = field(in, "op");
+ if (op != "get" && op != "wait" && op != "list" && op != "cancel")
+ throw fw::HttpError(422, "validation_error", "op must be get, wait, list or cancel");
+ return guarded([&] {
+ std::string name = field(in, "name");
+ if (op == "get") return sb::Operations::to_json(operations->get(name));
+ if (op == "wait")
+ return sb::Operations::to_json(operations->wait(name, static_cast(number(in, "timeout", 30))));
+ if (op == "cancel") {
+ operations->cancel(name);
+ Json o = Json::object();
+ o.set("cancel_requested", Json(name));
+ return o;
+ }
+ Json arr = Json::array();
+ for (const auto& e : operations->list(name, static_cast(number(in, "page_size", 0))))
+ arr.push(sb::Operations::to_json(e));
+ Json o = Json::object();
+ o.set("operations", arr);
+ return o;
+ });
+ });
+
+ // Removes the operation record, not the sandbox, template or snapshot.
+ router.del("/agent/sandbox/operation", "agent-sandbox-operation-delete", [operations](fw::Request req) {
+ std::string name = req.query_or("name", "");
+ return guarded([&] {
+ operations->remove(name);
+ Json o = Json::object();
+ o.set("deleted", Json(name));
+ return o;
+ });
+ });
+
+ router.post("/agent/sandbox/resource", "agent-sandbox-resource", [snapshots, templates](fw::Request req) {
+ Fields in = fields_of(req);
+ std::string kind = field(in, "kind");
+ if (kind != "template" && kind != "snapshot")
+ throw fw::HttpError(422, "validation_error", "kind must be template or snapshot");
+ return guarded([&] {
+ return kind == "template" ? templates->get(field(in, "name")).to_json()
+ : snapshots->get(field(in, "name")).to_json();
+ });
+ });
+
+ router.del("/agent/sandbox/resource", "agent-sandbox-resource-delete", [snapshots, templates](fw::Request req) {
+ std::string kind = req.query_or("kind", "");
+ std::string name = req.query_or("name", "");
+ if (kind != "template" && kind != "snapshot")
+ throw fw::HttpError(422, "validation_error", "kind must be template or snapshot");
+ return guarded([&] {
+ if (kind == "template") templates->remove(name);
+ else snapshots->remove(name);
+ Json o = Json::object();
+ o.set("deleted", Json(name));
+ return o;
+ });
+ });
+
+ router.post("/agent/sandbox/template", "agent-sandbox-template", [templates](fw::Request req) {
+ Fields in = fields_of(req);
+ sb::CreateTemplateRequest r;
+ r.display_name = field(in, "display_name");
+ std::string category = field(in, "category");
+ if (category == "computer") r.category = sb::ContainerCategory::kComputerUse;
+ else if (category == "shell") r.category = sb::ContainerCategory::kShellSandbox;
+ else if (!category.empty())
+ throw fw::HttpError(422, "validation_error", "category must be computer or shell");
+ r.internet_access = flag(in, "internet");
+ return guarded([&] { return templates->create(field(in, "engine"), r).to_json(); });
+ });
+
router.post("/agent/sandbox/files", "agent-sandbox-files", [shell](fw::Request req) {
Fields in = fields_of(req);
std::string op = field(in, "op");
diff --git a/src/google/sandbox/SPEC.md b/src/google/sandbox/SPEC.md
index f75ddd5..ae450dd 100644
--- a/src/google/sandbox/SPEC.md
+++ b/src/google/sandbox/SPEC.md
@@ -2,7 +2,8 @@
Owned directory: `src/google/sandbox/`. Namespace `molo::google::sandbox`.
Depends on the Google foundation (`GoogleClient`, `Service`, `GoogleError`,
-`wait_operation`, `list_all`, `CloudContext`) and the Base64 codec. No other
+`wait_operation`, `list_all`, `CloudContext`), the Base64 codec and the RFC 6455 client of
+`src/google/live` (`WsClient`, `open_stream`, used only by `CdpSession`). No other
module is included.
Purpose: create, inspect, pause, snapshot and delete Agent Sandbox
@@ -20,24 +21,46 @@ delete) and `sandboxEnvironmentSnapshots` (get, list, delete). A sandbox's
category is one of `codeExecutionEnvironment` (Python or JavaScript),
`computerUseEnvironment` (browser) or `shellEnvironment` (bash).
-**Workspaces.** No resource, method or schema named "workspace" exists in the
-`aiplatform` Discovery documents (v1 and v1beta1, checked 2026-10-24) and the
-sandbox docs index lists no workspace page. The product-level "Workspaces"
-(bash commands and file management isolated from core systems) is what the
-docs call the **shell sandbox**: `execute_bash` returns `stdout`, `stderr`,
-`returncode`, `duration_ms`, runs as an unprivileged user in `/workspace`, one
-fresh shell per command. This module implements that as `ShellRunner`.
-File management has no REST surface: `WorkspaceFiles` is a **local
-abstraction** that does file work with shell commands through `ShellRunner`.
-It is named local everywhere and is not a Google API.
+**Workspaces.** Re-checked 2026-10-24 (second pass): no resource, method or
+schema named "workspace" exists in the `aiplatform` Discovery documents (v1
+and v1beta1, 4.0 MB and 5.3 MB, case-insensitive search), none in the Python
+SDK 2.6.0 (`agentplatform/_genai`, `vertexai/_genai`: only `sandboxes`,
+`sandbox_templates`, `sandbox_snapshots`), and the docs index lists no
+workspace page. The platform overview still describes Workspaces as sandboxed
+environments to "run bash commands and manage files"; the docs call that the
+**shell sandbox**, and the SDK's own agent tool catalog
+(`_evals_builtin_tools.py`) shows file tools (`view_file`, `create_file`,
+`list_dir`, ...) as agent tools, not as REST. So there is still no REST
+surface. `ShellRunner` runs bash (`/exec`, see section 4) and `WorkspaceFiles`
+stays a **local abstraction** that does file work with shell commands. It is
+named local everywhere and is not a Google API.
-**Computer use.** The documented actions (navigate, click, type, screenshot)
-are Chrome DevTools Protocol commands sent to the sandbox data plane with a
-service-account JWT (`generate_access_token`, `send_command`, `/cdp`,
-`/tabs`, a CDP WebSocket for Playwright, VNC view). The data plane is not in
-Discovery. `ComputerUse` carries the same CDP commands through
-`sandboxEnvironments.execute`, the only sandbox call in the REST surface; that
-mapping is unverified (section 7).
+**Computer use.** Google documents two ways, both on the sandbox data plane
+(not in Discovery, documented by the computer use quickstart and implemented
+by the Python SDK 2.6.0, `Sandboxes.send_command` and
+`generate_browser_ws_headers`, read from the SDK source):
+
+- HTTP proxy: `https://{connectionInfo.loadBalancerHostname}` (or
+ `http://{loadBalancerIp}`, or the customer PSC endpoint for VPC-SC) with
+ headers `Authorization: Bearer `, `X-Sandbox-Routing-Token:
+ `, `X-Sandbox-Port: 8080`. Routes: `GET /`
+ health, `POST /tabs`, `GET /tabs`, `POST /tabs/{id}/activate`, `DELETE
+ /tabs/{id}`, `GET /cdp_ws_endpoint`, `POST /cdp` (one CDP command on the
+ active tab, body `{"command","params"}`), `POST /cdps` (several).
+- CDP WebSocket for Playwright `connect_over_cdp`: URL is the data plane host
+ (`wss://`) plus the `endpoint` path from `GET /cdp_ws_endpoint`; the only
+ auth is the header `Sec-WebSocket-Protocol: v1.stream, ,
+ , 9222`.
+
+The JWT is minted by `iamcredentials.googleapis.com` `projects.serviceAccounts.signJwt`
+(`POST v1/projects/-/serviceAccounts/{email}:signJwt`, body `{"payload":
+""}`) with claims `iat, exp (iat+3600), iss=sub=, nonce, aud="https://aiplatform.googleapis.com/"`. The caller needs
+`roles/aiplatform.user` and `roles/iam.serviceAccountTokenCreator` (docs).
+`ComputerUse` (navigate, click, type, screenshot, tabs, health, any CDP
+command) and `CdpSession` (CDP over the WebSocket) implement this. The shell
+sandbox needs none of it: `execute_bash` authenticates with the caller's own
+credentials through `sandboxEnvironments.execute` (docs and SDK).
## 2. Module map (one class or concern per file)
@@ -55,8 +78,13 @@ mapping is unverified (section 7).
| `code_executor.h/.cpp` | `CodeExecutor`: code plus input files in, typed result out |
| `shell_runner.h/.cpp` | `ShellRunner`: bash command with cwd and timeout |
| `workspace_files.h/.cpp` | `WorkspaceFiles` (local): write, read, list, remove_file |
-| `computer_use.h/.cpp` | `ComputerUse`: navigate, click, type_text, screenshot |
-| `stream_executor.h/.cpp` | `StreamExecutor`: `bidiExecute` (v1beta1), streamed reply |
+| `jwt.h/.cpp` | `ITokenSource`, `IamJwtSource`: signJwt-minted data plane JWT, cache, refresh margin, invalidate |
+| `data_plane.h/.cpp` | `DataPlaneTarget` (address from connectionInfo), `DataPlane` (HTTP proxy: health, tabs, `/cdp`, `/cdps`, `/cdp_ws_endpoint`, header placement, one refresh on 401) |
+| `cdp_session.h/.cpp` | `CdpSession`: CDP JSON-RPC over the WebSocket (reuses `live::WsClient`), events, reconnect cap |
+| `data_plane_connector.h/.cpp` | `DataPlaneOptions`, `DataPlaneConnector`: sandbox name to `DataPlane` / `CdpSession` |
+| `computer_use.h/.cpp` | `ComputerUse`: navigate, click, type_text, screenshot, tabs, health, CDP command, over the data plane |
+| `operations.h/.cpp` | `Operations`: get, wait, cancel, delete (v1), list (v1beta1) for the three resources |
+| `stream_executor.h/.cpp` | `StreamExecutor`: `bidiExecute` (v1beta1), one request message, streamed reply (REST form, see section 7) |
| `tools/check_discovery.py` | Discovery check for `calls.h` |
## 3. Static caps (see caps.h)
@@ -80,7 +108,15 @@ mapping is unverified (section 7).
| List page size / pages | 100 (Google default and ceiling) / 10 |
| Template ports / disk | 16 / 1..1024 GB |
| URL / typed text / coordinate | 2048 / 4096 / 0..10000 |
+| Input chunks per execute | 17 (one code chunk plus 16 files) |
| Stream events | 256 |
+| Data plane JWT ttl / refresh margin | 60..3600 s (default 3600) / refresh inside the last 300 s, one refresh per call after a 401 |
+| Data plane reply / error excerpt / batch | 8 MiB / 512 bytes / 32 commands |
+| Data plane timeout | default 30 s, max 120 s; no redirects, no automatic retries |
+| Routing token / host / path / tab id | 4096 / 253 / 256 / 128 chars |
+| CDP message / buffered events / call timeout | 8 MiB / 256 (oldest dropped and counted) / 30 s default, 120 s max |
+| CDP reconnects / floor between connects | 3 per session, ever / 250 ms |
+| Operations wait | 1..120 s server side |
| LRO wait | foundation `wait_operation`: 600 s, 400 polls |
Google's own limit is 100 MB of files per request or response. Ours are
@@ -109,24 +145,55 @@ again inside the Chunk, and the codec caps base64 input at 16 MiB.
Over-cap or unsafe files are never dropped silently: each gets a reason in
`skipped`. `ok()` is true when the exit status is absent or 0.
- `Chunk.data` and `Metadata.attributes` values are base64 on the wire
- (Discovery: `format: byte`); the codec exposes raw bytes.
-- Computer use accepts only `http://` and `https://` URLs.
+ (Discovery: `format: byte`; the SDK models both as bytes); the codec exposes
+ raw bytes. An attribute value that is not base64 makes the chunk invalid and
+ it is skipped loudly, never guessed.
+- Input chunks (SDK `execute_code` / `execute_bash`): code is one
+ `application/json` chunk `{"code": ...}` followed by one chunk per input file
+ (its mime type, raw bytes, attribute `file_name`); shell is three chunks, mime
+ `application/x.sandbox-request-uri` data `/exec`, mime
+ `application/x.sandbox-request-port` data `8080`, then `application/json`
+ `{"command","cwd","timeout"}`.
+- Data plane: the JWT is sent only to the address derived from the sandbox's
+ own `connectionInfo` (or a caller-supplied PSC endpoint); redirects are off;
+ a loopback override is accepted for loopback hosts only. Order of checks in
+ `DataPlaneConnector::open`: name, credential (503), signer (503), sandbox
+ read, `STATE_RUNNING` (409), address. A 401 refreshes the JWT once.
+- CDP commands are never replayed: a connection lost during a call throws
+ `CDP_CONNECTION_LOST`; the next call reconnects (fresh JWT, endpoint
+ re-resolved, at most 3 reconnects per session). Session ids from before a
+ reconnect are void.
+- Operations: `delete` removes the operation record, not the resource; `cancel`
+ and `delete` are explicit methods.
+- Computer use accepts only `http://` and `https://` URLs. The data plane needs a service account to sign
+ with (`GOOGLE_SERVICE_ACCOUNT_EMAIL`, else `client_email` of
+ `GOOGLE_APPLICATION_CREDENTIALS`); without one calls answer 503 NOT_CONFIGURED.
## 5. Verified against discovery
`python3 -I src/google/sandbox/tools/check_discovery.py` fetches
`https://aiplatform.googleapis.com/$discovery/rest?version=v1` and `v1beta1`
-and fails when any row of `calls.h` is absent: 18 calls (rpc id, HTTP method,
-path, request body field paths including nested ones), 21 schemas (field
-names) and 7 enums (values).
+(and `iamcredentials` `v1`) and fails when any row of `calls.h` is absent:
+34 calls (rpc id, HTTP method, path, request body field paths including nested
+ones), 27 schemas (field names) and 7 enums (values).
-Result on 2026-10-24: `18 calls, 21 schemas, 7 enums, 204 checks, 0 missing`.
+Result on 2026-10-24: `34 calls, 27 schemas, 7 enums, 268 checks, 0 missing`.
Findings from the check that shaped the code: `computerUseEnvironment`,
`useGkeTd` and `persistentDiskConfig` exist only in `v1beta1`; `bidiExecute`
exists only in `v1beta1`; `PauseSandboxEnvironmentRequest`,
`ResumeSandboxEnvironmentRequest` and `AuthorizeSandboxEnvironmentAccessRequest`
have no fields; the snapshot request body is a `SandboxEnvironmentSnapshot`
-whose `sourceSandboxEnvironment` is required.
+whose `sourceSandboxEnvironment` is required; the operations methods
+(`get`, `wait`, `cancel`, `delete`) exist in `v1` and `v1beta1`, `list` only in
+`v1beta1` (`GET v1beta1/{+name}/operations`, `name` is the sandbox, template or
+snapshot); `wait` takes a `timeout` query parameter (google-duration).
+
+Method coverage: every Discovery method under `sandboxEnvironments`,
+`sandboxEnvironmentTemplates` and `sandboxEnvironmentSnapshots` of
+`projects.locations.reasoningEngines` is wrapped or declared: 10 sandbox
+methods, 4 template, 3 snapshot, 5 operations per resource (15). Not wrapped
+on purpose: the project-less aliases (`reasoningEngines.sandbox*`), and the
+operations of the reasoning engine itself (owned by the runtime module).
## 6. Verified live
@@ -155,8 +222,26 @@ statuses and bodies, so the key reaches these read routes too. A made-up
collection (`.../bogusThings`) answers an HTML 404 page, and a non-numeric
engine id (`none`) answers 400 INVALID_ARGUMENT; engine ids are numeric.
+Second pass 2026-10-24 (same credentials, read-only):
+
+| Call | Status and body |
+|---|---|
+| `GET v1beta1/.../sandboxEnvironments/{absent}/operations?pageSize=5` | 200 `{}` (empty list, not 404) |
+| `GET v1/.../sandboxEnvironments/{absent}/operations/1` | 404 NOT_FOUND "Operation projects/P/.../operations/1 not found." |
+| same for `.../sandboxEnvironmentTemplates/{absent}/operations/1` and `.../sandboxEnvironmentSnapshots/{absent}/operations/1` | 404 NOT_FOUND, same message shape |
+| `POST iamcredentials v1/projects/-/serviceAccounts/{email}:signJwt` with the SDK payload | 403 PERMISSION_DENIED: "IAM Service Account Credentials API has not been used in project N before or it is disabled" |
+
+The signJwt answer proves the route, path and body shape reach the service;
+it stops at the project not having the IAM Credentials API enabled. It was not
+enabled here (that changes the project; an owner decision). Hence no data plane
+JWT has ever been minted by this module against Google, and the data plane was
+never reached: the project has no engine, so no sandbox, so no `connectionInfo`
+and no proxy address. The whole data plane is verified by the SDK source and
+docs (section 9) plus loopback mechanics tests, not by Google replies.
+
Never exercised live (Discovery only): create, pause, resume, snapshot,
-delete, execute, bidiExecute, authorizeAccess, template create and delete,
+delete, execute, bidiExecute, authorizeAccess, wait/cancel/delete of operations,
+template create and delete, the data plane (HTTP proxy and CDP WebSocket),
and every response shape of an existing sandbox. Whether a key may mutate
sandboxes is unknown.
@@ -166,57 +251,88 @@ google-test` (a key in `GOOGLE_API_KEY` also works). Test
sandboxes of an engine id that cannot exist and gets a sandbox that cannot
exist, expecting 404 NOT_FOUND through the real client; it creates nothing.
It passed on 2026-10-24 with the OAuth token and with the key.
+`google_live_sandbox.operations_read_only` and `google_live_sandbox.sign_jwt_probe`
+cover the second-pass rows above (the second accepts 403 or 400 and prints the status).
Gemini's built-in `codeExecution` tool inside `generateContent` belongs to the
models module and is not used here.
-## 7. Unverified
+## 7. Settled and Unverified
-Neither Discovery nor the docs state these; each is inferred and isolated in
-`ChunkCodec` so one edit fixes it:
+Settled from primary sources on 2026-10-24 (no Google reply seen, because no
+sandbox exists and none may be created):
-- The payload of an input Chunk. Docs show only the SDK call
- (`execute_code(input_data={"code":..., "files":[{"name","content"}]})`) and
- an older doc revision says input file content is base64. Assumed: one
- `application/json` Chunk holding `{"code", "files":[{"name","content"(base64)}]}`.
-- The payload of a shell input Chunk. Assumed `{"command","cwd","timeout"}`
- (names from the SDK helper `execute_bash(command, cwd, timeout)`).
-- The payload of a computer use input Chunk: `{"command":"Page.navigate",
- "params":{...}}` is the documented `/cdp` body; sending it through `execute`
- is assumed. Click is `Input.dispatchMouseEvent` pressed then released, typing
- is `Input.insertText`, screenshot is `Page.captureScreenshot` (CDP names, not
- Google names).
-- Output Chunk payloads: docs show an `application/json` Chunk with `msg_out`,
- `msg_err`, `output_files[{content (base64)}]`, plus Chunks with a `file_name`
- attribute. The `name` key inside `output_files` and the shell keys `stdout`,
- `stderr`, `returncode`, `duration_ms` (seen only in the SDK dict) are
- assumed. Unknown shapes are skipped loudly, never guessed.
-- Whether `attributes` values are really base64 on the wire (Discovery says
- `byte`; docs show plain text). The decoder tries base64 and falls back to the
- text as written.
-- Whether `bidiExecute` over this client's POST stream behaves as a server
- stream; it is a bidirectional method and may need a persistent channel.
-- Which responses carry which `@type` inside an Operation `response`
- (`SandboxEnvironment`, `SandboxEnvironmentSnapshot`, template); parsed by
+- Input chunks for code and shell, the shell output keys (`stdout`, `stderr`,
+ `returncode`, `duration_ms`), the code output keys (`msg_out`, `msg_err`,
+ `output_files[].content` base64) and file chunks with the `file_name`
+ attribute: Python SDK 2.6.0 `execute_code` / `execute_bash` source, the shell
+ and code execution quickstarts. Attribute values are bytes, base64 on the
+ wire: Discovery `format: byte` for `Metadata.attributes`, SDK `bytes`.
+- CDP command body `{"command","params"}` for `POST /cdp`, the endpoint list,
+ the `/cdp_ws_endpoint` reply key `endpoint`, the three headers, the
+ `Sec-WebSocket-Protocol` form, the JWT claims: computer use quickstart and
+ SDK source.
+- Workspaces have no REST surface (Discovery, SDK, docs index).
+
+Still unverified; each is inferred and isolated in one function:
+
+- The reply body shapes of the data plane. Docs and SDK show only that the
+ body is returned as text. `ComputerUse::result_of` accepts `{"result": {...}}`
+ or the object itself; the screenshot is the base64 `data` of a CDP
+ `Page.captureScreenshot` result. A reply with neither is `EMPTY_RESPONSE`.
+- The request body of `POST /cdps` (`{"commands":[{"command","params"}...]}` is
+ our reading of "runs multiple CDP commands") and whether `POST /tabs` takes a
+ body (we send none).
+- The output key `name` inside `output_files` (docs show only `content`). The
+ decoder reads `name` or `file_name` and skips a nameless file loudly.
+- `Chunk.mimeType` of file input chunks when the caller gives none: we guess
+ from the extension, the SDK sends an empty string.
+- Whether the CDP WebSocket answers browser-level (`Target.*`) or page-level
+ commands first; `CdpSession::attach_first_page` uses flat sessions
+ (`Target.attachToTarget {flatten:true}`), the standard Chrome mode that
+ Playwright also uses over this endpoint.
+- Frame size: `live::LiveCaps::kMaxFramePayload` (4 MiB) caps one WebSocket
+ frame. A base64 screenshot larger than that fails over the WebSocket
+ (`TooBig`); use `ComputerUse::screenshot` (HTTP) for large pages.
+- `bidiExecute`: Discovery gives one `POST ...:bidiExecute` with a request body
+ of `inputs` and a response of `outputs`, described as "bidirectional
+ streaming". Over REST the request is one message and the reply a stream;
+ `StreamExecutor` does exactly that over the real HTTP transport (mechanics
+ tested against a loopback server). Whether Google's REST gateway accepts
+ further input messages on the same call is not documented, so true
+ full-duplex input is not offered.
+- Which responses carry which `@type` inside an Operation `response`; parsed by
field name only.
-- The `filter` list parameter exists (AIP-160) but its grammar is not
- documented; it is not exposed.
+- The `filter` list parameter (AIP-160 grammar not documented) and
+ `returnPartialSuccess` of operations list are not exposed.
+- Execution paths (execute, bidiExecute, data plane) have never run against
+ Google; they are verified by Discovery, docs and SDK source, and by local
+ mechanics tests only.
## 8. Gaps
-- The sandbox data plane (HTTP proxy with JWT, `/tabs`, `/cdp`, CDP
- WebSocket, VNC) is not implemented; it needs a service-account JWT signer
- (foundation gap in `credentials.cpp`) and a WebSocket client (module `live`).
- Owner of the follow-up: this module, `computer_use.cpp`.
-- True bidirectional `bidiExecute` input (see Unverified).
-- `generate_access_token` and `generate_browser_ws_headers` (SDK helpers) have
- no REST method in Discovery.
+- The data plane needs the IAM Credentials API enabled on the project and
+ `roles/iam.serviceAccountTokenCreator` for the signing account; neither could
+ be checked (the API is disabled on `lisa-448004`, section 6). Owner:
+ project administrator.
+- The data plane cannot be reached without a running sandbox, which this
+ project does not have and must not create from here. First live run:
+ create an engine and a computer use template and sandbox, then
+ `POST /agent/sandbox/dataplane {action:health}`; the reply shapes in
+ section 7 are then read and settled.
+- VNC streaming view (noVNC over WebSocket) is documented but without any
+ connection detail; not implemented.
- Template update, custom container resources/requests, DNS peering, private
service connect ingress, CMEK and VPC-SC settings are not typed. Templates
- keep the whole document in `SandboxTemplate::raw`.
+ keep the whole document in `SandboxTemplate::raw`. VPC-SC data plane access
+ works only with a caller-supplied PSC endpoint (`DataPlaneOptions::psc_endpoint`).
- Foundation: `Service::call` always posts to the one endpoint a service was
built with; this module needs a different location and version per call, so
`SandboxService` builds endpoints itself and talks to `GoogleClient`
- directly.
+ directly. The data plane host is not a Google API host, so it uses its own
+ `clients::Client` over the real HTTP transport with the JWT and routing
+ headers (the foundation client applies only Google credentials).
+- `live::LiveCaps` (module `live`, not editable here) fixes the WebSocket frame
+ cap at 4 MiB; a request to raise it belongs to that module.
- The example server's flat JSON reader does not decode `\n`; the demo uses
the real JSON parser for request bodies.
@@ -229,6 +345,12 @@ Neither Discovery nor the docs state these; each is inferred and isolated in
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/shell-sandbox-quickstart
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/manage-sandboxes
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1beta1/projects.locations.reasoningEngines.sandboxEnvironments (and its `create`, `execute`, `list`, `delete`, `pause`, `authorizeAccess` pages) and `.../v1beta1/Chunk`
+- Python SDK `google-cloud-aiplatform` 2.6.0 (PyPI), files `agentplatform/_genai/sandboxes.py` (`execute_code`, `execute_bash`, `generate_access_token`, `send_command`, `generate_browser_ws_headers`), `sandbox_templates.py`, `sandbox_snapshots.py`, `_evals_builtin_tools.py`
+- https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/computer-use-quickstart (JWT, `send_command`, endpoint table) and `.../computer-use` (`generate_browser_ws_headers`, `connect_over_cdp`, VNC)
+- https://docs.cloud.google.com/gemini-enterprise-agent-platform/release-notes (2026-09-09: Computer Use and Shell sandboxes GA, direct API `/exec`)
+- https://iamcredentials.googleapis.com/$discovery/rest?version=v1 (`signJwt`)
+- https://chromedevtools.github.io/devtools-protocol/ (CDP JSON-RPC, flat sessions, `Target`, `Page`, `Input`)
+- https://www.rfc-editor.org/rfc/rfc6455 (WebSocket, via `src/google/live`)
- https://aiplatform.googleapis.com/$discovery/rest?version=v1
- https://aiplatform.googleapis.com/$discovery/rest?version=v1beta1
- Not read (listed on the docs index): `manage-templates`, `manage-snapshots`,
@@ -239,7 +361,15 @@ Neither Discovery nor the docs state these; each is inferred and isolated in
`example/app/agent/SandboxDemo.cpp`, page script `example/assets/agent_sandbox.js`.
GET `/agent/sandbox` (page, matrix row `agent-sandbox`), GET
-`/agent/sandbox/status`. POST `/agent/sandbox/{create,list,get,pause,resume,
-snapshot,snapshots,templates,execute,shell,computer,files}`, DELETE
-`/agent/sandbox/delete?name=`. Without a credential every Google route is 503
-`google_not_configured`; bad input is 422. Tests: `tests/example/agent/sandbox/`.
+`/agent/sandbox/status` (includes `data_plane_signer`, a boolean). POST
+`/agent/sandbox/{create,list,get,pause,resume,snapshot,snapshots,templates,
+execute,shell,computer,files,dataplane,cdp,stream,operations,resource,template}`,
+DELETE `/agent/sandbox/delete?name=`, DELETE `/agent/sandbox/operation?name=`,
+DELETE `/agent/sandbox/resource?kind=template|snapshot&name=`. `dataplane`
+covers health, tabs and any CDP command over HTTP; `cdp` opens the WebSocket
+for one call (optionally attaching the first page) and closes it; `stream` is
+`bidiExecute`; `operations` is get, wait, list, cancel. Without a credential
+(or without a service account for the data plane) every Google route is 503
+`google_not_configured`; bad input is 422. Tests: `tests/example/agent/sandbox/`
+(route tests) and `tests/src/google/sandbox/` (module tests, loopback data
+plane in `test_sandbox_dataplane.cpp`).
diff --git a/src/google/sandbox/calls.h b/src/google/sandbox/calls.h
index 4170d47..b79a45c 100644
--- a/src/google/sandbox/calls.h
+++ b/src/google/sandbox/calls.h
@@ -53,6 +53,22 @@ inline constexpr DeclaredCall kDeclaredCalls[] = {
{"snapshot.get", "GET", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.get", ""},
{"snapshot.list", "GET", "{+parent}/sandboxEnvironmentSnapshots", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.list", ""},
{"snapshot.delete", "DELETE", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.delete", ""},
+ {"sandbox.operation.get", "GET", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironments.operations.get", ""},
+ {"sandbox.operation.wait", "POST", "{+name}:wait", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironments.operations.wait", ""},
+ {"sandbox.operation.cancel", "POST", "{+name}:cancel", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironments.operations.cancel", ""},
+ {"sandbox.operation.delete", "DELETE", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironments.operations.delete", ""},
+ {"sandbox.operation.list", "GET", "{+name}/operations", "aiplatform", "v1beta1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironments.operations.list", ""},
+ {"template.operation.get", "GET", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentTemplates.operations.get", ""},
+ {"template.operation.wait", "POST", "{+name}:wait", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentTemplates.operations.wait", ""},
+ {"template.operation.cancel", "POST", "{+name}:cancel", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentTemplates.operations.cancel", ""},
+ {"template.operation.delete", "DELETE", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentTemplates.operations.delete", ""},
+ {"template.operation.list", "GET", "{+name}/operations", "aiplatform", "v1beta1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentTemplates.operations.list", ""},
+ {"snapshot.operation.get", "GET", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.operations.get", ""},
+ {"snapshot.operation.wait", "POST", "{+name}:wait", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.operations.wait", ""},
+ {"snapshot.operation.cancel", "POST", "{+name}:cancel", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.operations.cancel", ""},
+ {"snapshot.operation.delete", "DELETE", "{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.operations.delete", ""},
+ {"snapshot.operation.list", "GET", "{+name}/operations", "aiplatform", "v1beta1", "aiplatform.projects.locations.reasoningEngines.sandboxEnvironmentSnapshots.operations.list", ""},
+ {"iam.signJwt", "POST", "{+name}:signJwt", "iamcredentials", "v1", "iamcredentials.projects.serviceAccounts.signJwt", "payload,delegates"},
};
// CALLS-END
@@ -79,6 +95,12 @@ inline constexpr DeclaredSchema kDeclaredSchemas[] = {
{"aiplatform", "v1beta1", "SandboxEnvironmentTemplateEgressControlConfig", "internetAccess,networkAttachment,dnsPeeringConfigs"},
{"aiplatform", "v1beta1", "SandboxEnvironmentTemplatePersistentDiskConfig", "enabled,mountPath,sizeGb"},
{"aiplatform", "v1beta1", "ListSandboxEnvironmentTemplatesResponse", "sandboxEnvironmentTemplates,nextPageToken"},
+ {"aiplatform", "v1beta1", "SandboxEnvironmentConnectionInfo", "loadBalancerIp,loadBalancerHostname,sandboxInternalIp,routingToken,serviceAttachment"},
+ {"aiplatform", "v1beta1", "BidiExecuteSandboxEnvironmentRequest", "inputs"},
+ {"aiplatform", "v1beta1", "Chunk", "mimeType,data,metadata"},
+ {"aiplatform", "v1beta1", "Metadata", "attributes"},
+ {"iamcredentials", "v1", "SignJwtRequest", "payload,delegates"},
+ {"iamcredentials", "v1", "SignJwtResponse", "keyId,signedJwt"},
};
// SCHEMAS-END
diff --git a/src/google/sandbox/caps.h b/src/google/sandbox/caps.h
index 1cab407..807da42 100644
--- a/src/google/sandbox/caps.h
+++ b/src/google/sandbox/caps.h
@@ -13,6 +13,8 @@ struct SandboxCaps {
static constexpr std::size_t kMaxCommandBytes = 8192;
static constexpr std::size_t kMaxInternalCommandBytes = 65536; // Workspace helpers only.
static constexpr std::size_t kMaxInputFiles = 16;
+ // One JSON code chunk plus one chunk per file.
+ static constexpr std::size_t kMaxInputChunks = 1 + kMaxInputFiles;
static constexpr std::size_t kMaxFileBytes = 4u * 1024u * 1024u;
static constexpr std::size_t kMaxInputTotalBytes = 8u * 1024u * 1024u;
static constexpr std::size_t kMaxFileNameChars = 255;
@@ -49,6 +51,37 @@ struct SandboxCaps {
static constexpr std::size_t kMaxUrlChars = 2048;
static constexpr std::size_t kMaxTypedChars = 4096;
static constexpr int kMaxCoordinate = 10000;
+
+ // Data plane (HTTP proxy and CDP WebSocket). All static ceilings.
+ static constexpr long kJwtTtlSeconds = 3600; // SDK default
+ static constexpr long kMinJwtTtlSeconds = 60;
+ static constexpr long kMaxJwtTtlSeconds = 3600; // never longer than an hour
+ static constexpr long kJwtRefreshMarginSeconds = 300; // refresh when this close to exp
+ static constexpr std::size_t kMaxEmailChars = 254;
+ static constexpr std::size_t kMaxRoutingTokenChars = 4096;
+ static constexpr std::size_t kMaxHostChars = 253;
+ static constexpr std::size_t kMaxDataPathChars = 256;
+ static constexpr std::size_t kMaxTabIdChars = 128;
+ static constexpr std::size_t kMaxDataReplyBytes = 8u * 1024u * 1024u;
+ static constexpr std::size_t kMaxErrorExcerpt = 512;
+ static constexpr std::size_t kMaxBatchCommands = 32;
+ static constexpr int kDataPlaneTimeoutMs = 30000;
+ static constexpr int kMaxDataPlaneTimeoutMs = 120000;
+ static constexpr int kMaxAuthRetries = 1; // one JWT refresh after a 401
+
+ // CDP over WebSocket.
+ static constexpr int kCdpConnectTimeoutMs = 10000;
+ static constexpr int kCdpCallTimeoutMs = 30000;
+ static constexpr int kMaxCdpCallTimeoutMs = 120000;
+ static constexpr int kCdpPollMs = 200;
+ static constexpr std::size_t kMaxCdpEvents = 256; // buffered, oldest dropped and counted
+ static constexpr std::size_t kMaxCdpMessageChars = 8u * 1024u * 1024u;
+ static constexpr std::size_t kMaxCdpMethodChars = 128;
+ static constexpr int kMaxCdpReconnects = 3; // per session, ever
+ static constexpr int kMinReconnectGapMs = 250; // floor between connects
+ static constexpr std::size_t kMaxCdpSessionIdChars = 128;
+ // Operations.
+ static constexpr int kMaxOperationWaitSeconds = 120;
};
} // namespace molo::google::sandbox
diff --git a/src/google/sandbox/cdp_session.cpp b/src/google/sandbox/cdp_session.cpp
new file mode 100644
index 0000000..dfbf401
--- /dev/null
+++ b/src/google/sandbox/cdp_session.cpp
@@ -0,0 +1,274 @@
+#include "google/sandbox/cdp_session.h"
+
+#include
+#include
+#include
+#include
+
+#include "google/errors.h"
+#include "google/live/ws_error.h"
+#include "google/live/ws_url.h"
+#include "google/resource.h"
+#include "google/sandbox/caps.h"
+
+namespace molo::google::sandbox {
+
+using clients::body::Json;
+
+namespace {
+
+constexpr const char* kService = "sandbox-cdp";
+
+long now_ms() {
+ return static_cast(std::chrono::duration_cast(
+ std::chrono::steady_clock::now().time_since_epoch())
+ .count());
+}
+
+GoogleError lost(const std::string& why) {
+ return GoogleError(502, "CDP_CONNECTION_LOST", why, kService);
+}
+
+} // namespace
+
+CdpSession::CdpSession(std::shared_ptr plane, CdpOptions options)
+ : plane_(std::move(plane)), options_(std::move(options)) {
+ if (!plane_) throw GoogleError::invalid("a data plane is required");
+ if (options_.connect_timeout_ms == 0) options_.connect_timeout_ms = SandboxCaps::kCdpConnectTimeoutMs;
+ if (options_.call_timeout_ms == 0) options_.call_timeout_ms = SandboxCaps::kCdpCallTimeoutMs;
+ if (options_.connect_timeout_ms < 100 || options_.connect_timeout_ms > SandboxCaps::kMaxCdpCallTimeoutMs ||
+ options_.call_timeout_ms < 100 || options_.call_timeout_ms > SandboxCaps::kMaxCdpCallTimeoutMs)
+ throw GoogleError::invalid("timeouts must be 100.." +
+ std::to_string(SandboxCaps::kMaxCdpCallTimeoutMs) + " ms");
+ DataPlaneTarget::validate_port(options_.browser_port);
+}
+
+CdpSession::~CdpSession() {
+ try {
+ close();
+ } catch (...) {
+ }
+}
+
+void CdpSession::validate_session_id(const std::string& id) {
+ if (id.size() > SandboxCaps::kMaxCdpSessionIdChars)
+ throw GoogleError::invalid("session id too long");
+ for (char c : id)
+ if (!std::isalnum(static_cast(c)) && c != '-' && c != '_')
+ throw GoogleError::invalid("session id has an invalid character");
+}
+
+Json CdpSession::request(long id, const std::string& method, const Json& params,
+ const std::string& session_id) {
+ DataPlane::validate_command(method);
+ if (!params.is_object()) throw GoogleError::invalid("CDP params must be a JSON object");
+ validate_session_id(session_id);
+ Json m = Json::object();
+ m.set("id", Json(id));
+ m.set("method", Json(method));
+ m.set("params", params);
+ if (!session_id.empty()) m.set("sessionId", Json(session_id));
+ return m;
+}
+
+bool CdpSession::connected() const { return ws_ && !ws_->closed(); }
+
+void CdpSession::open_socket() {
+ // Floor between connection attempts: a flapping peer is never hammered.
+ if (last_connect_ms_ != 0) {
+ long gap = now_ms() - last_connect_ms_;
+ if (gap < SandboxCaps::kMinReconnectGapMs)
+ std::this_thread::sleep_for(std::chrono::milliseconds(SandboxCaps::kMinReconnectGapMs - gap));
+ }
+ last_connect_ms_ = now_ms();
+ if (endpoint_path_.empty()) endpoint_path_ = plane_->cdp_ws_endpoint();
+ for (int attempt = 0;; ++attempt) {
+ try {
+ live::WsUrl url = live::WsUrl::parse(plane_->ws_url(endpoint_path_));
+ live::WsHeaders headers = plane_->ws_headers(options_.browser_port);
+ auto stream = live::open_stream(url, options_.connect_timeout_ms, 1000);
+ auto ws = std::make_unique(std::move(stream));
+ ws->handshake(url, headers, options_.connect_timeout_ms);
+ ws->set_read_timeout_ms(SandboxCaps::kCdpPollMs);
+ ws_ = std::move(ws);
+ ++connects_;
+ return;
+ } catch (const live::WsError& e) {
+ bool auth = e.kind() == live::WsError::Kind::Handshake &&
+ (e.http_status() == 401 || e.http_status() == 403);
+ if (auth && attempt < SandboxCaps::kMaxAuthRetries) {
+ plane_->tokens().invalidate();
+ continue;
+ }
+ throw GoogleError(auth ? e.http_status() : 502, auth ? "CDP_UNAUTHORIZED" : "UNAVAILABLE",
+ e.what(), kService);
+ }
+ }
+}
+
+void CdpSession::connect() {
+ if (connected()) return;
+ open_socket();
+}
+
+void CdpSession::ensure_connected() {
+ if (connected()) return;
+ if (connects_ > 0) {
+ // A socket that existed and died: a capped reconnect with a fresh JWT.
+ if (reconnects_ >= SandboxCaps::kMaxCdpReconnects)
+ throw GoogleError(502, "CDP_RECONNECT_LIMIT",
+ "more than " + std::to_string(SandboxCaps::kMaxCdpReconnects) +
+ " reconnects; open a new session",
+ kService);
+ ++reconnects_;
+ plane_->tokens().invalidate();
+ endpoint_path_.clear();
+ }
+ open_socket();
+}
+
+void CdpSession::close() {
+ if (ws_) {
+ try {
+ ws_->close(1000, "");
+ ws_->shutdown();
+ } catch (...) {
+ }
+ ws_.reset();
+ }
+}
+
+void CdpSession::push_event(Json event) {
+ if (events_.size() >= SandboxCaps::kMaxCdpEvents) {
+ events_.pop_front();
+ ++dropped_events_;
+ }
+ events_.push_back(std::move(event));
+}
+
+// Reads for up to budget_ms. Returns true once the reply with wanted_id
+// (>= 0) arrived in *reply. Every other message with an id is dropped, every
+// message without one is buffered as an event.
+bool CdpSession::pump(int budget_ms, long wanted_id, Json* reply) {
+ long deadline = now_ms() + budget_ms;
+ for (;;) {
+ if (now_ms() >= deadline) return false;
+ std::optional m;
+ try {
+ m = ws_->receive();
+ } catch (const live::WsError& e) {
+ ws_.reset();
+ throw lost(e.what());
+ }
+ if (!m) continue;
+ if (m->kind == live::WsMessage::Kind::Close) {
+ ws_.reset();
+ throw lost("peer closed the CDP socket (code " + std::to_string(m->code) + ")");
+ }
+ if (m->data.size() > SandboxCaps::kMaxCdpMessageChars)
+ throw GoogleError(502, "TOO_BIG", "CDP message over cap", kService);
+ Json doc;
+ try {
+ doc = Json::parse(m->data);
+ } catch (const clients::body::JsonError&) {
+ continue; // Not CDP; never guessed at.
+ }
+ if (!doc.is_object()) continue;
+ const Json* id = doc.find("id");
+ if (id && id->is_number()) {
+ if (wanted_id >= 0 && id->as_int() == wanted_id) {
+ *reply = std::move(doc);
+ return true;
+ }
+ continue;
+ }
+ push_event(std::move(doc));
+ if (wanted_id < 0) return true; // Caller scans the buffer.
+ }
+}
+
+Json CdpSession::call(const std::string& method, const Json& params, const std::string& session_id,
+ int timeout_ms) {
+ long id = next_id_;
+ Json msg = request(id, method, params, session_id);
+ if (timeout_ms == 0) timeout_ms = options_.call_timeout_ms;
+ if (timeout_ms < 100 || timeout_ms > SandboxCaps::kMaxCdpCallTimeoutMs)
+ throw GoogleError::invalid("timeout must be 100.." +
+ std::to_string(SandboxCaps::kMaxCdpCallTimeoutMs) + " ms");
+ ensure_connected();
+ ++next_id_;
+ try {
+ ws_->send_text(msg.dump());
+ } catch (const live::WsError& e) {
+ ws_.reset();
+ throw GoogleError(e.kind() == live::WsError::Kind::TooBig ? 400 : 502,
+ e.kind() == live::WsError::Kind::TooBig ? "INVALID_ARGUMENT" : "CDP_CONNECTION_LOST",
+ e.what(), e.kind() == live::WsError::Kind::TooBig ? "" : kService);
+ }
+ Json reply;
+ if (!pump(timeout_ms, id, &reply))
+ throw GoogleError(504, "DEADLINE_EXCEEDED", "no CDP reply to " + method + " in " +
+ std::to_string(timeout_ms) + " ms", kService);
+ if (const Json* err = reply.find("error"); err && err->is_object()) {
+ const Json* m = err->find("message");
+ throw GoogleError(502, "CDP_ERROR", m && m->is_string() ? m->as_string() : "CDP error", kService);
+ }
+ const Json* result = reply.find("result");
+ return result && result->is_object() ? *result : Json::object();
+}
+
+std::string CdpSession::attach_first_page() {
+ Json targets = call("Target.getTargets", Json::object());
+ const Json* infos = targets.find("targetInfos");
+ if (!infos || !infos->is_array())
+ throw GoogleError(502, "BAD_RESPONSE", "Target.getTargets returned no targetInfos", kService);
+ for (const Json& t : infos->as_array()) {
+ const Json* type = t.find("type");
+ const Json* tid = t.find("targetId");
+ if (type && type->is_string() && type->as_string() == "page" && tid && tid->is_string()) {
+ Json p = Json::object();
+ p.set("targetId", Json(tid->as_string()));
+ p.set("flatten", Json(true));
+ Json r = call("Target.attachToTarget", p);
+ const Json* sid = r.find("sessionId");
+ if (!sid || !sid->is_string() || sid->as_string().empty())
+ throw GoogleError(502, "BAD_RESPONSE", "attachToTarget returned no sessionId", kService);
+ validate_session_id(sid->as_string());
+ return sid->as_string();
+ }
+ }
+ throw GoogleError(404, "NOT_FOUND", "the browser has no page target", kService);
+}
+
+std::vector CdpSession::take_events() {
+ std::vector out(events_.begin(), events_.end());
+ events_.clear();
+ return out;
+}
+
+Json CdpSession::wait_event(const std::string& method, int timeout_ms) {
+ DataPlane::validate_command(method);
+ if (timeout_ms == 0) timeout_ms = options_.call_timeout_ms;
+ if (timeout_ms < 100 || timeout_ms > SandboxCaps::kMaxCdpCallTimeoutMs)
+ throw GoogleError::invalid("timeout must be 100.." +
+ std::to_string(SandboxCaps::kMaxCdpCallTimeoutMs) + " ms");
+ ensure_connected();
+ long deadline = now_ms() + timeout_ms;
+ for (;;) {
+ for (auto it = events_.begin(); it != events_.end(); ++it) {
+ const Json* m = it->find("method");
+ if (m && m->is_string() && m->as_string() == method) {
+ Json ev = *it;
+ events_.erase(it);
+ return ev;
+ }
+ }
+ long left = deadline - now_ms();
+ if (left <= 0)
+ throw GoogleError(504, "DEADLINE_EXCEEDED", "no CDP event " + method, kService);
+ Json unused;
+ pump(static_cast(left), -1, &unused);
+ }
+}
+
+} // namespace molo::google::sandbox
diff --git a/src/google/sandbox/cdp_session.h b/src/google/sandbox/cdp_session.h
new file mode 100644
index 0000000..69ee705
--- /dev/null
+++ b/src/google/sandbox/cdp_session.h
@@ -0,0 +1,93 @@
+#pragma once
+
+// Chrome DevTools Protocol over the sandbox's CDP WebSocket (computer use).
+// Connects like the Google SDK's `generate_browser_ws_headers` plus
+// Playwright's connect_over_cdp: GET /cdp_ws_endpoint on the HTTP data plane
+// gives a path, the WebSocket URL is the data plane host plus that path, and
+// the JWT travels in the Sec-WebSocket-Protocol header
+// ("v1.stream, , , 9222"). Messages are CDP JSON-RPC
+// ({"id","method","params"[,"sessionId"]}), see
+// https://chromedevtools.github.io/devtools-protocol/ (flat session mode).
+//
+// Reuses the RFC 6455 client of src/google/live (WsClient, open_stream).
+// Hard caps: message size, buffered events, call time, reconnects, and a
+// floor between connection attempts. One thread uses a session at a time.
+
+#include
+#include
+#include
+#include
+
+#include "google/live/ws_client.h"
+#include "google/sandbox/data_plane.h"
+
+namespace molo::google::sandbox {
+
+struct CdpOptions {
+ int connect_timeout_ms = 0; // 0: SandboxCaps default
+ int call_timeout_ms = 0; // 0: SandboxCaps default
+ std::string browser_port = "9222";
+};
+
+class CdpSession {
+ public:
+ CdpSession(std::shared_ptr plane, CdpOptions options = {});
+ ~CdpSession();
+
+ CdpSession(const CdpSession&) = delete;
+ CdpSession& operator=(const CdpSession&) = delete;
+
+ // Resolves the endpoint, mints a JWT and runs the upgrade. Idempotent.
+ void connect();
+ bool connected() const;
+ // Sends a polite close and drops the socket.
+ void close();
+
+ // Sends one CDP command and waits for its reply (matched by id). Returns the
+ // "result" object. A CDP "error" object throws GoogleError 502
+ // CDP_ERROR with Chrome's message. A lost socket before the send is
+ // reconnected (fresh JWT, capped); a loss mid-call throws CDP_CONNECTION_LOST
+ // and the next call reconnects, because commands are never replayed. Session
+ // ids from before a reconnect are void.
+ clients::body::Json call(const std::string& method, const clients::body::Json& params,
+ const std::string& session_id = "", int timeout_ms = 0);
+
+ // Browser-level helper: Target.getTargets, Target.attachToTarget
+ // {flatten:true} for the first "page" target; returns the sessionId.
+ std::string attach_first_page();
+
+ // Events (messages without id) seen while waiting, oldest first; at most
+ // kMaxCdpEvents are kept, older ones are dropped and counted.
+ std::vector take_events();
+ // Waits for an event with this method (already buffered or newly read).
+ clients::body::Json wait_event(const std::string& method, int timeout_ms = 0);
+
+ int connects() const { return connects_; }
+ int reconnects() const { return reconnects_; }
+ std::size_t dropped_events() const { return dropped_events_; }
+ const std::string& endpoint_path() const { return endpoint_path_; }
+
+ static void validate_session_id(const std::string& id);
+ static clients::body::Json request(long id, const std::string& method,
+ const clients::body::Json& params,
+ const std::string& session_id);
+
+ private:
+ void open_socket();
+ void ensure_connected();
+ bool pump(int budget_ms, long wanted_id, clients::body::Json* reply);
+ void push_event(clients::body::Json event);
+
+ std::shared_ptr plane_;
+ CdpOptions options_;
+ std::unique_ptr ws_;
+ std::string endpoint_path_;
+ long next_id_ = 1;
+ int connects_ = 0;
+ int reconnects_ = 0;
+ long last_connect_ms_ = 0;
+ std::deque events_;
+ std::size_t dropped_events_ = 0;
+};
+
+} // namespace molo::google::sandbox
diff --git a/src/google/sandbox/chunk.cpp b/src/google/sandbox/chunk.cpp
index 7128445..d40f699 100644
--- a/src/google/sandbox/chunk.cpp
+++ b/src/google/sandbox/chunk.cpp
@@ -1,5 +1,10 @@
#include "google/sandbox/chunk.h"
+#include
+#include