Documentation
¶
Overview ¶
Package bots is a bot doing your work on a real desktop, live, while you watch.
It 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 (apps/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 BotRun ¶ added in v1.801.350
type BotRun struct {
// RunID is the run's id in the bot runtime, and the node id its live VNC session
// is registered under.
RunID string `json:"runId"`
// Task is the instruction the bot is executing.
Task string `json:"task"`
// Surface is what the bot drives: the desktop or terminal sandbox it runs in.
Surface string `json:"surface"`
// Status is the run's state as the runtime reports it; "running" when the runtime
// names none of its own.
Status string `json:"status"`
// SessionURL is the live session the hanzo.app /vnc panel embeds to watch or
// attach to this run. Derived here from the run id, never sent by the runtime.
SessionURL string `json:"sessionUrl"`
// StartedAt is when the run began, RFC 3339, as the runtime stamped it.
StartedAt string `json:"startedAt"`
}
BotRun is one row of GET /v1/bots — the console list item. sessionUrl is derived control-plane side from runId (the ONE place a session URL is built), so the runtime never has to know its own public origin.
The name is qualified because the fleet's schema namespace is FLAT and apps/visor already publishes a `botView` for a bot MACHINE (a box you rent). This is a bot RUN. Two values, two names.
type BotRuns ¶ added in v1.801.350
type BotRuns struct {
// Bots is the org's live runs. Always an array, never null.
Bots []BotRun `json:"bots"`
}
BotRuns is the GET /v1/bots envelope; Bots is always non-nil so an org with no runs serializes as {"bots":[]}, never {"bots":null}.
type BotStopped ¶ added in v1.801.350
type BotStopped struct {
// RunID is the run that was stopped.
RunID string `json:"runId"`
// Status is the run's terminal state: "stopped".
Status string `json:"status"`
}
BotStopped is the POST /v1/bots/{runId}/stop receipt.
type Run ¶
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 ¶
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