Files
retoorandClaude Sonnet 5.5 1c3fbe1899 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>
2026-10-24 05:30:44 +02:00

561 lines
25 KiB
C++

#include "../AgentDemos.hpp"
#include <map>
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "../../fw/Validate.hpp"
#include "google/client.h"
#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"
#include "google/sandbox/templates.h"
#include "google/sandbox/workspace_files.h"
#include "security/crypto/Base64.h"
namespace molo::example::app {
// Agent Platform: sandbox. Agent Sandbox (code execution, computer use, shell
// "workspaces") over src/google/sandbox. Every route that reaches Google is a
// POST (or DELETE) and answers 503 google_not_configured without a credential
// and 422 on bad input. Nothing is created unless the caller asks.
namespace {
namespace sb = google::sandbox;
using Json = clients::body::Json;
using Fields = std::map<std::string, std::string>;
// The framework's flat parser does not decode \n and friends, which code
// needs, so the body goes through the real JSON parser. Scalars become text.
Fields fields_of(const fw::Request& req) {
Fields out;
if (req.body.empty()) return out;
Json doc;
try {
doc = Json::parse(req.body);
} catch (const clients::body::JsonError&) {
throw fw::HttpError(422, "validation_error", "body must be a JSON object");
}
if (!doc.is_object())
throw fw::HttpError(422, "validation_error", "body must be a JSON object");
for (const auto& [k, v] : doc.as_object()) {
if (v.is_string()) out[k] = v.as_string();
else if (v.is_number()) out[k] = std::to_string(v.as_int());
else if (v.is_bool()) out[k] = v.as_bool() ? "true" : "false";
}
return out;
}
std::string field(const Fields& in, const char* key) {
auto it = in.find(key);
return it == in.end() ? std::string() : it->second;
}
long number(const Fields& in, const char* key, long fallback) {
std::string v = field(in, key);
if (v.empty()) return fallback;
if (v.size() > 12 || v.find_first_not_of("0123456789") != std::string::npos)
throw fw::HttpError(422, "validation_error", std::string(key) + " must be a whole number");
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());
if (e.service().empty() && e.status() == "INVALID_ARGUMENT")
throw fw::HttpError(422, "validation_error", e.message());
throw fw::HttpError(502, "google_error", e.status() + ": " + e.message());
}
template <typename F>
fw::Response guarded(F&& f) {
try {
Json out = f();
fw::Response res = fw::JsonResponse(out.dump(), 200);
res.headers.set("Cache-Control", "no-store");
return res;
} catch (const google::GoogleError& e) {
rethrow(e);
}
}
sb::SandboxSpec spec_of(const Fields& in) {
sb::SandboxSpec spec;
if (!sb::kind_from_name(field(in, "kind").empty() ? "code" : field(in, "kind"), spec.kind))
throw fw::HttpError(422, "validation_error", "kind must be code, computer or shell");
if (!sb::language_from_name(field(in, "language"), spec.language))
throw fw::HttpError(422, "validation_error", "language must be python or javascript");
if (field(in, "machine") == "4cpu") spec.machine = sb::MachineConfig::kVcpu4Ram4Gib;
return spec;
}
Json caps_json() {
Json c = Json::object();
auto n = [](std::size_t v) { return Json(static_cast<long>(v)); };
c.set("max_code_bytes", n(sb::SandboxCaps::kMaxCodeBytes));
c.set("max_command_bytes", n(sb::SandboxCaps::kMaxCommandBytes));
c.set("max_input_files", n(sb::SandboxCaps::kMaxInputFiles));
c.set("max_file_bytes", n(sb::SandboxCaps::kMaxFileBytes));
c.set("max_output_bytes", n(sb::SandboxCaps::kMaxOutputBytes));
c.set("max_produced_files", n(sb::SandboxCaps::kMaxProducedFiles));
c.set("max_shell_timeout_seconds", Json(sb::SandboxCaps::kMaxShellTimeoutSeconds));
c.set("ttl_seconds_min", Json(sb::SandboxCaps::kMinTtlSeconds));
c.set("ttl_seconds_max", Json(sb::SandboxCaps::kMaxTtlSeconds));
c.set("max_url_chars", n(sb::SandboxCaps::kMaxUrlChars));
c.set("max_typed_chars", n(sb::SandboxCaps::kMaxTypedChars));
return c;
}
const char kPage[] = R"SANDBOX({% extends "base.html" %}
{% block content %}
<h1>Agent sandbox</h1>
<p class="hint">Run model-written code, shell commands and browser actions in
Google's isolated sandboxes. Resource names look like
projects/P/locations/L/reasoningEngines/E/sandboxEnvironments/S. Needs an
OAuth token (GOOGLE_ACCESS_TOKEN); every call is capped.</p>
<p id="sb-config" class="hint">Checking Google credentials...</p>
<p id="sb-error" class="error" role="alert"></p>
<form class="sb-form" data-route="/agent/sandbox/create">
<h2>Create</h2>
<input name="engine" placeholder="reasoning engine name" required>
<input name="display_name" placeholder="display name" required>
<select name="kind"><option value="code">code</option><option value="shell">shell</option><option value="computer">computer</option></select>
<select name="language"><option value="">default language</option><option value="python">python</option><option value="javascript">javascript</option></select>
<input name="ttl_seconds" placeholder="ttl seconds (3600)">
<input name="template" placeholder="template name (computer use)">
<button type="submit">Create</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/list">
<h2>List</h2>
<input name="engine" placeholder="reasoning engine name" required>
<button type="submit">List sandboxes</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/execute">
<h2>Run code</h2>
<input name="name" placeholder="sandbox name" required>
<textarea name="code" rows="5" placeholder="print('hello')" required></textarea>
<button type="submit">Run</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/shell">
<h2>Shell command</h2>
<input name="name" placeholder="sandbox name" required>
<input name="command" placeholder="echo hello" required>
<input name="timeout" placeholder="timeout seconds (30)">
<button type="submit">Run</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/computer">
<h2>Computer use</h2>
<input name="name" placeholder="sandbox name" required>
<select name="action"><option value="navigate">navigate</option><option value="click">click</option><option value="type">type</option><option value="screenshot">screenshot</option></select>
<input name="url" placeholder="https://example.com">
<input name="x" placeholder="x"><input name="y" placeholder="y">
<input name="text" placeholder="text to type">
<button type="submit">Send</button>
</form>
<form class="sb-form" data-route="/agent/sandbox/files">
<h2>Workspace files</h2>
<input name="name" placeholder="sandbox name" required>
<select name="op"><option value="list">list</option><option value="read">read</option><option value="write">write</option></select>
<input name="path" placeholder="path under /workspace">
<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 %}
)SANDBOX";
} // namespace
void register_agent_sandbox_demo(fw::Router& router, Services& services) {
if (!services.google) services.google = google::GoogleClient::from_env();
auto client = services.google;
services.templates->add_template("agent_sandbox.html", kPage);
fw::Environment* env = services.templates.get();
services.add_feature("agent-sandbox", "/agent/sandbox");
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 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);
router.get("/agent/sandbox", "agent-sandbox-page", [env](fw::Request) {
fw::TemplateCtx ctx;
ctx["title"] = std::string("Agent sandbox");
return fw::Response(200, env->render("agent_sandbox.html", ctx),
"text/html; charset=utf-8");
});
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, 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;
});
router.post("/agent/sandbox/create", "agent-sandbox-create", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
sb::CreateSandboxRequest r;
r.display_name = field(in, "display_name");
r.spec = spec_of(in);
r.ttl_seconds = number(in, "ttl_seconds", sb::SandboxCaps::kDefaultTtlSeconds);
r.template_name = field(in, "template");
r.snapshot_name = field(in, "snapshot");
return guarded([&] { return sandboxes->create(field(in, "engine"), r).to_json(); });
});
router.post("/agent/sandbox/list", "agent-sandbox-list", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] {
Json arr = Json::array();
for (const auto& s : sandboxes->list(field(in, "engine"))) arr.push(s.to_json());
Json o = Json::object();
o.set("sandboxes", arr);
return o;
});
});
router.post("/agent/sandbox/get", "agent-sandbox-get", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] { return sandboxes->get(field(in, "name")).to_json(); });
});
router.post("/agent/sandbox/pause", "agent-sandbox-pause", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] { return sandboxes->pause(field(in, "name")).to_json(); });
});
router.post("/agent/sandbox/resume", "agent-sandbox-resume", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] { return sandboxes->resume(field(in, "name")).to_json(); });
});
router.post("/agent/sandbox/snapshot", "agent-sandbox-snapshot", [sandboxes](fw::Request req) {
Fields in = fields_of(req);
sb::SnapshotRequest r;
r.display_name = field(in, "display_name");
r.ttl_seconds = number(in, "ttl_seconds", 0);
r.post_action = field(in, "post_action");
return guarded([&] { return sandboxes->snapshot(field(in, "name"), r).to_json(); });
});
router.post("/agent/sandbox/snapshots", "agent-sandbox-snapshots", [snapshots](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] {
Json arr = Json::array();
for (const auto& s : snapshots->list(field(in, "engine"))) arr.push(s.to_json());
Json o = Json::object();
o.set("snapshots", arr);
return o;
});
});
router.post("/agent/sandbox/templates", "agent-sandbox-templates", [templates](fw::Request req) {
Fields in = fields_of(req);
return guarded([&] {
Json arr = Json::array();
for (const auto& t : templates->list(field(in, "engine"))) arr.push(t.to_json());
Json o = Json::object();
o.set("templates", arr);
return o;
});
});
// Deleting is its own route and verb; nothing else deletes.
router.del("/agent/sandbox/delete", "agent-sandbox-delete", [sandboxes](fw::Request req) {
std::string name = req.query_or("name", "");
return guarded([&] {
sandboxes->remove(name);
Json o = Json::object();
o.set("deleted", Json(name));
return o;
});
});
router.post("/agent/sandbox/execute", "agent-sandbox-execute", [code](fw::Request req) {
Fields in = fields_of(req);
std::vector<sb::InputFile> files;
if (!field(in, "file_name").empty()) {
std::string raw;
if (!security::crypto::Base64::decode(field(in, "file_b64"), raw))
throw fw::HttpError(422, "validation_error", "file_b64 must be base64");
files.push_back({field(in, "file_name"), raw});
}
return guarded([&] { return code->run(field(in, "name"), field(in, "code"), files).to_json(); });
});
router.post("/agent/sandbox/shell", "agent-sandbox-shell", [shell](fw::Request req) {
Fields in = fields_of(req);
sb::ShellRequest r;
r.command = field(in, "command");
r.cwd = field(in, "cwd");
r.timeout_seconds = static_cast<int>(number(in, "timeout", sb::SandboxCaps::kDefaultShellTimeoutSeconds));
return guarded([&] { return shell->run(field(in, "name"), r).to_json(); });
});
router.post("/agent/sandbox/computer", "agent-sandbox-computer", [computer](fw::Request req) {
Fields in = fields_of(req);
std::string action = field(in, "action");
if (action != "navigate" && action != "click" && action != "type" && action != "screenshot")
throw fw::HttpError(422, "validation_error",
"action must be navigate, click, type or screenshot");
return guarded([&] {
std::string name = field(in, "name");
sb::ActionResult r;
if (action == "navigate") r = computer->navigate(name, field(in, "url"));
else if (action == "click")
r = computer->click(name, static_cast<int>(number(in, "x", -1)),
static_cast<int>(number(in, "y", -1)));
else if (action == "type") r = computer->type_text(name, field(in, "text"));
else r = computer->screenshot(name);
Json o = Json::object();
o.set("result", r.result);
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");
if (op != "list" && op != "read" && op != "write")
throw fw::HttpError(422, "validation_error", "op must be list, read or write");
return guarded([&] {
sb::WorkspaceFiles files(*shell);
std::string name = field(in, "name");
Json o = Json::object();
if (op == "list") {
Json arr = Json::array();
for (const std::string& e : files.list(name, field(in, "path"))) arr.push(Json(e));
o.set("entries", arr);
} else if (op == "read") {
o.set("content_b64", Json(security::crypto::Base64::encode(files.read(name, field(in, "path")))));
} else {
files.write(name, field(in, "path"), field(in, "content"));
o.set("written", Json(field(in, "path")));
}
return o;
});
});
}
} // namespace molo::example::app