bots

Overview ¶

Package bots mounts the Hanzo Cloud POST /v1/bots/run surface: launch a computer-using agent (a "bot") — a booted desktop or terminal sandbox the operative computer-use runtime drives to do a task — and hand back a LIVE session (the URL the hanzo.app /vnc panel embeds to watch/attach).

This handler is a THIN ORCHESTRATOR, deliberately. It does NOT boot machines, speak VNC, or reimplement visor: those live in the separate TS `bot` service (its gateway exposes the browser<->gateway<->node HMAC VNC tunnel at /vnc?nodeId=<id>) and in visor (machine provisioning). This handler owns the three things a cloud control-plane owns:

1. authenticate the caller (a run MOVES MONEY, so a VALIDATED principal is required — never a bare, forgeable org header);
2. gate + meter the run against the caller's OWN org ledger (a flat per-run fee, the same ResourceMeter path every non-LLM resource uses);
3. mint the run id and return the session descriptor whose sessionUrl points at the bot VNC gateway for that run.

Tenant isolation is the gateway-minted X-Org-Id (HIP-0026), resolved via principal.Org and NEVER read from the request body — so one tenant can never launch, or bill, a bot against another's org.

Surface (org-scoped; the CLI `hanzo bot run` calls it):

POST /v1/bots/run  {task, surface, gpu, timeout}  -> {runId, status, sessionUrl}

The billed unit is a flat per-RUN fee — the honest, policy-set unit a bot launch bills. GB-seconds / GPU-hour metering is intentionally NOT fabricated here: this endpoint launches the run, it does not observe its runtime footprint (visor/bot-gateway do). The fee is ops-configurable per deployment via cloud.ResourceFeeCents(botFeeEnvPrefix, meterKind); set it to 0 to make bot launches free (and therefore un-gated), exactly like the agents run fee.