Documentation
¶
Overview ¶
Package bots is the CONTROL PLANE for a bot run: a task the bot runtime executes on a surface — a desktop or terminal sandbox it drives — with a LIVE session (the URL the hanzo.app /vnc panel embeds to watch/attach).
A bot run is ONE value with ONE home. It is not the bot MACHINE that hosts a runtime (visor's /v1/compute/bots — a machine you rent), and it is not the runtime service itself (clients/runtime — the transport to the executor).
CLOUD OWNS POLICY, THE RUNTIME OWNS THE RUN. The sandbox lives in the runtime, keyed in the runtime's own store under the tenant that started it; that store is the only thing that knows whether a run is alive. So this package keeps no second copy of it. It owns what a control plane owns — who you are, which org you are, and whether you may — and then asks the runtime, which IS the registry. Copying that state into cloud would create a second id space agreeing with nothing: listing runs that do not exist and stopping runs never started.
Isolation: the org is the gateway-minted X-Org-Id (HIP-0026) resolved via principal.Org, NEVER a request field, and it is what cloud sends the runtime, which keys every run under tenants/{org}/. A caller cannot name another tenant's org, so it cannot read or stop another tenant's runs; a foreign run id resolves under the CALLER's org, where it does not exist, and answers 404.
Surface (org-scoped; the console BotsApi and the CLI `hanzo bot run` call it):
POST /v1/bots/run -> 501: no runtime launch operation exists yet
GET /v1/bots -> {bots:[{runId,task,surface,status,sessionUrl,startedAt}]}
POST /v1/bots/:runId/stop -> {runId, status}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Run ¶ added in v1.801.37
type Run struct {
ID string
Task string
Surface string
Status string
StartedAt string // RFC3339, as the runtime stamps it
}
Run is one bot run as the runtime reports it.
type Runtime ¶ added in v1.801.37
type Runtime interface {
List(ctx context.Context, org string) ([]Run, error)
Stop(ctx context.Context, org, runID string) error
}
Runtime is the seam onto the run registry — the bot runtime, which owns the sandboxes and is therefore the only truthful answer to "what is running". Bound to the real transport in wire.go; a fake in tests.
Every method takes org FIRST and the runtime scopes by it. The seam carries no authority: cloud decides WHETHER a caller may ask, the runtime answers WHAT it holds for that org.
Source Files