feat(clients): sandbox: data plane (JWT proxy, CDP WebSocket), operations, SDK chunk shapes

Data plane per the computer use quickstart and SDK 2.6.0 source: signJwt
minted JWT, /cdp /tabs /cdp_ws_endpoint over HTTP with routing headers, CDP
over the live WsClient with capped reconnect. Operations methods wrapped,
input/output chunk shapes settled from the SDK, ComputerUse moved off execute.
Execution paths remain verified by Discovery, docs and SDK only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 05:30:44 +02:00
co-authored by Claude Sonnet 5.5
parent 29d775a923
commit 1c3fbe1899
33 changed files with 3031 additions and 185 deletions
+208 -4
View File
@@ -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.</p>
<textarea name="content" rows="3" placeholder="content (write)"></textarea>
<button type="submit">Go</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/dataplane">
<h2>Data plane (computer use)</h2>
<input name="name" placeholder="sandbox name" required>
<select name="action"><option value="health">health</option><option value="tabs">list tabs</option><option value="new_tab">new tab</option><option value="activate">activate tab</option><option value="close">close tab</option><option value="command">CDP command</option></select>
<input name="tab_id" placeholder="tab id">
<input name="command" placeholder="Page.navigate">
<input name="params" placeholder='{"url":"https://example.com"}'>
<button type="submit">Send</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/cdp">
<h2>CDP WebSocket</h2>
<input name="name" placeholder="sandbox name" required>
<input name="method" placeholder="Page.navigate" required>
<input name="params" placeholder='{"url":"https://example.com"}'>
<select name="page"><option value="true">attach first page</option><option value="false">browser level</option></select>
<button type="submit">Call</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/stream">
<h2>Streamed execute (bidiExecute)</h2>
<input name="name" placeholder="sandbox name" required>
<select name="mode"><option value="shell">shell</option><option value="code">code</option></select>
<textarea name="input" rows="3" placeholder="command or code" required></textarea>
<button type="submit">Run</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/operations">
<h2>Operations</h2>
<input name="name" placeholder="operation name, or a resource name for list" required>
<select name="op"><option value="get">get</option><option value="wait">wait</option><option value="list">list</option><option value="cancel">cancel</option></select>
<input name="timeout" placeholder="wait seconds (30)">
<button type="submit">Go</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/resource">
<h2>Template or snapshot</h2>
<input name="name" placeholder="template or snapshot name" required>
<select name="kind"><option value="template">template</option><option value="snapshot">snapshot</option></select>
<button type="submit">Get</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/template">
<h2>Create template</h2>
<input name="engine" placeholder="reasoning engine name" required>
<input name="display_name" placeholder="display name" required>
<select name="category"><option value="computer">computer use</option><option value="shell">shell</option></select>
<select name="internet"><option value="false">no internet</option><option value="true">internet access</option></select>
<button type="submit">Create</button>
</form>
<pre id="sb-out" class="sb-out"></pre>
<script src="/embedded/agent_sandbox.js"></script>
{% endblock %}
@@ -181,7 +243,10 @@ void register_agent_sandbox_demo(fw::Router& router, Services& services) {
auto sandboxes = std::make_shared<sb::Sandboxes>(client);
auto code = std::make_shared<sb::CodeExecutor>(client);
auto shell = std::make_shared<sb::ShellRunner>(client);
auto computer = std::make_shared<sb::ComputerUse>(client);
auto connector = std::make_shared<sb::DataPlaneConnector>(client, sb::DataPlaneOptions::from_env());
auto computer = std::make_shared<sb::ComputerUse>(client, connector);
auto operations = std::make_shared<sb::Operations>(client);
auto streamer = std::make_shared<sb::StreamExecutor>(client);
auto snapshots = std::make_shared<sb::Snapshots>(client);
auto templates = std::make_shared<sb::Templates>(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<sb::CdpSession> 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<long>(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<sb::Chunk> inputs =
mode == "shell" ? sb::ChunkCodec::shell_inputs(field(in, "input"), field(in, "cwd"),
static_cast<int>(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<int>(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<int>(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<int>(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");