#include "../AgentDemos.hpp" #include #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; // 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 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(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 %}

Agent sandbox

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.

Checking Google credentials...

Create

List

Run code

Shell command

Computer use

Workspace files

Data plane (computer use)

CDP WebSocket

Streamed execute (bidiExecute)

Operations

Template or snapshot

Create template



{% 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(client);
  auto code = std::make_shared(client);
  auto shell = 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);

  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 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(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(number(in, "x", -1)),
                            static_cast(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 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");
    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