controlplane

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package controlplane is runeward's governed execution core. Every tool call runs through one path: policy, approval gate, guardrails, backend exec, audit ledger. The Manager owns sandbox sessions and the shared ledger; the REST and MCP servers are thin adapters over it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Approval 

type Approval struct {
	ID      string
	Sandbox string
	Tool    string
	Action  string
	Reason  string
	Created time.Time
	// contains filtered or unexported fields
}

Approval is a pending human-in-the-loop authorization request. The blocked tool call waits on decided until an operator resolves it.

type ApprovalStore 

type ApprovalStore struct {
	// contains filtered or unexported fields
}

ApprovalStore is a concurrency-safe registry of pending approvals.

func NewApprovalStore 

func NewApprovalStore() *ApprovalStore

NewApprovalStore returns an empty store.

func (*ApprovalStore) Create 

func (s *ApprovalStore) Create(sandbox, tool, action, reason string) *Approval

Create registers a new pending approval and returns it.

func (*ApprovalStore) List 

func (s *ApprovalStore) List() []ApprovalView

List returns a snapshot of pending approvals in map order; callers sort if they need to.

func (*ApprovalStore) Resolve 

func (s *ApprovalStore) Resolve(id string, approve bool) bool

Resolve delivers a decision to the waiting tool call and removes the approval. It reports whether that id was pending.

func (*ApprovalStore) ResolveView 

func (s *ApprovalStore) ResolveView(id string, approve bool) (ApprovalView, bool)

ResolveView is like Resolve but also returns a view of the approval that was resolved, so callers can record who decided it and what it authorized.

type ApprovalView 

type ApprovalView struct {
	ID      string    `json:"id"`
	Sandbox string    `json:"sandbox"`
	Tool    string    `json:"tool"`
	Action  string    `json:"action"`
	Reason  string    `json:"reason"`
	Created time.Time `json:"created"`
}

ApprovalView is the JSON projection of an Approval.

type ClientError 

type ClientError struct {
	// NotFound marks a missing resource (sandbox, fleet, snapshot, browser
	// session) -> 404. When false the error is treated as bad input -> 400.
	NotFound bool
	Message  string
}

ClientError is an error whose message is safe to return to an API caller and which maps to a client-facing HTTP status. It lets the server distinguish bad input and missing resources (which the caller can act on) from genuine internal failures, which must stay opaque so they cannot leak host paths, backend detail, or other server-side information.

func (*ClientError) Error 

func (e *ClientError) Error() string

type CreateOptions 

type CreateOptions struct {
	// CopyFrom overrides host.copy_from for this create: a one-time copy into
	// the fresh workspace, the host dir is never mounted. "~/" is expanded.
	CopyFrom string
	// Owner records the RBAC principal that created the sandbox, for
	// per-principal visibility and access control. Empty means unowned
	// (RBAC disabled), in which case every caller can see it.
	Owner string
}

CreateOptions carries per-create overrides that are not part of the profile.

type Fleet 

type Fleet struct {
	ID        string
	Profile   string
	Owner     string
	Board     *fleet.Board
	Sandboxes []string
	Created   time.Time
	// contains filtered or unexported fields
}

Fleet is a set of sandboxes from one profile sharing an atomic task board.

type FleetView 

type FleetView struct {
	ID        string      `json:"id"`
	Profile   string      `json:"profile"`
	Owner     string      `json:"owner,omitempty"`
	Sandboxes []string    `json:"sandboxes"`
	Stats     fleet.Stats `json:"stats"`
	Created   time.Time   `json:"created"`
}

FleetView is the JSON projection of a fleet.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the control-plane core. It is safe for concurrent use.

func New 

func New(configDir string) (*Manager, error)

New constructs a Manager and opens the shared audit ledger.

func (*Manager) AddTask 

func (m *Manager) AddTask(fleetID, payload string) (*fleet.Task, error)

AddTask appends a task to a fleet's board.

func (*Manager) Approvals 

func (m *Manager) Approvals() *ApprovalStore

Approvals returns the approval store.

func (*Manager) AttachTerminal 

func (m *Manager) AttachTerminal(ctx context.Context, id string, stream backend.PTYStream) error

AttachTerminal wires an interactive PTY to the sandbox. Terminals are not policy-gated per keystroke, but the attach itself is audited.

func (*Manager) Browser 

func (m *Manager) Browser(ctx context.Context, id, url, mode string) (*ToolResult, error)

Browser renders a page with headless Chromium inside the sandbox. It is policy-gated as tool "browser" (arg = url), and the profile's egress proxy is passed via --proxy-server so egress rules cover browser traffic too. mode is "text" (rendered DOM HTML) or "screenshot" (base64 PNG in Stdout).

func (*Manager) BrowserAct 

func (m *Manager) BrowserAct(ctx context.Context, id, sessionID string, cmd browser.Command) (*ToolResult, error)

BrowserAct sends one action to a live browser session through the governed path. Stdout carries the value (or base64 screenshot); a driver-level failure surfaces in Reason.

func (*Manager) BrowserClose 

func (m *Manager) BrowserClose(ctx context.Context, id, sessionID string) error

BrowserClose shuts down the driver (best-effort) and always removes local bookkeeping.

func (*Manager) BrowserOpen 

func (m *Manager) BrowserOpen(ctx context.Context, id string) (sessionID string, res *ToolResult, err error)

BrowserOpen starts a stateful CDP browser session in the sandbox and returns its id. The driver is launched detached; the egress proxy is threaded through via --proxy. Gated by policy as tool "browser" (action "open"), so a deny or pending verdict comes back in the ToolResult without starting a session.

func (*Manager) ClaimTask 

func (m *Manager) ClaimTask(fleetID, owner string) (fleet.Task, bool, error)

ClaimTask atomically claims the next pending task for a worker.

func (*Manager) Close 

func (m *Manager) Close() error

Close stops the sweeper, flushes audit sinks, and releases the ledger handle.

func (*Manager) CompleteTask 

func (m *Manager) CompleteTask(fleetID, taskID, owner, result string) error

CompleteTask marks a claimed task done. owner must match the claiming worker.

func (*Manager) CreateFleet 

func (m *Manager) CreateFleet(ctx context.Context, profileName string) (*FleetView, error)

CreateFleet provisions the profile's replicas with a shared task board seeded from its task_board list.

func (*Manager) CreateFleetForOwner 

func (m *Manager) CreateFleetForOwner(ctx context.Context, profileName, owner string) (*FleetView, error)

CreateFleetForOwner provisions the profile's replicas with a shared task board seeded from its task_board list and attributes member sandboxes to the owning principal when provided.

func (*Manager) CreateSandbox 

func (m *Manager) CreateSandbox(ctx context.Context, profileName string, opts CreateOptions) (*backend.Sandbox, error)

CreateSandbox loads the named profile, provisions a sandbox on its backend, and registers a governed session for it.

func (*Manager) ExportBundle 

func (m *Manager) ExportBundle(w io.Writer, sessionID string) error

ExportBundle writes a verifiable transcript of a session's audit events (all events when sessionID is "") to w. Fails when signing is disabled.

func (*Manager) FailTask 

func (m *Manager) FailTask(fleetID, taskID, owner, errMsg string, requeue bool) error

FailTask marks a claimed task failed, optionally requeuing it. owner must match the claiming worker.

func (*Manager) FileList 

func (m *Manager) FileList(ctx context.Context, id, path string) (*ToolResult, error)

FileList lists a directory in the sandbox.

func (*Manager) FileRead 

func (m *Manager) FileRead(ctx context.Context, id, path string) (*ToolResult, error)

FileRead returns the contents of a file in the sandbox.

func (*Manager) FileSearch 

func (m *Manager) FileSearch(ctx context.Context, id, query, path string) (*ToolResult, error)

FileSearch runs a recursive grep rooted at path.

func (*Manager) FileWrite 

func (m *Manager) FileWrite(ctx context.Context, id, path, content string) (*ToolResult, error)

FileWrite writes a file in the sandbox, creating parent directories. Content travels base64-encoded to stay binary-safe over the shell.

func (*Manager) FleetView 

func (m *Manager) FleetView(id string) (*FleetView, bool)

FleetView returns a single fleet's projection.

func (*Manager) HeartbeatTask 

func (m *Manager) HeartbeatTask(fleetID, taskID, owner string) (fleet.Task, error)

HeartbeatTask extends a worker's lease on a task so the sweeper won't requeue it.

func (*Manager) KillFleet 

func (m *Manager) KillFleet(ctx context.Context, id string) error

KillFleet tears down every sandbox in the fleet and removes it.

func (*Manager) KillSandbox 

func (m *Manager) KillSandbox(ctx context.Context, id string) error

KillSandbox tears down a sandbox and removes its session.

func (*Manager) Ledger 

func (m *Manager) Ledger() *ledger.Ledger

Ledger returns the shared ledger.

func (*Manager) LedgerPublicKey 

func (m *Manager) LedgerPublicKey() (pub string, keyID string)

LedgerPublicKey returns the base64 signing key and key id, or empty strings when signing is disabled.

func (*Manager) ListFleets 

func (m *Manager) ListFleets() []FleetView

ListFleets returns all fleets.

func (*Manager) ListProfiles 

func (m *Manager) ListProfiles() ([]ProfileInfo, error)

ListProfiles returns the resolvable profiles for the configured search path.

func (*Manager) ListSandboxInfos 

func (m *Manager) ListSandboxInfos() []SandboxInfo

ListSandboxInfos returns every governed sandbox together with its owner. The server uses this to filter the list per principal ("multi-user" views).

func (*Manager) ListSandboxes 

func (m *Manager) ListSandboxes() []backend.Sandbox

ListSandboxes returns handles for every governed sandbox.

func (*Manager) ListSnapshots 

func (m *Manager) ListSnapshots() []backend.SnapshotRef

ListSnapshots returns all captured snapshot references.

func (*Manager) ListTasks 

func (m *Manager) ListTasks(fleetID string) ([]fleet.Task, error)

ListTasks returns a snapshot of a fleet's tasks.

func (*Manager) Node 

func (m *Manager) Node(ctx context.Context, id, code string) (*ToolResult, error)

Node runs a JavaScript snippet via `node -e`.

func (*Manager) Python 

func (m *Manager) Python(ctx context.Context, id, code string) (*ToolResult, error)

Python runs a Python snippet via `python3 -c`.

func (*Manager) RecordUsage 

func (m *Manager) RecordUsage(id string, tokens int64, costUSD float64) error

RecordUsage attributes reported model usage (tokens and/or US-dollar spend) to a sandbox, updating the accounting totals and metrics and appending an audit event. Callers (agents, fleet workers) report usage they observe from the model provider; once the profile's budget is exceeded, govern denies further tool calls. It errors if the sandbox is unknown.

func (*Manager) ResolveApproval 

func (m *Manager) ResolveApproval(id string, approve bool, actor string) bool

ResolveApproval resolves a pending approval and records who decided it in the tamper-evident ledger, so a human-in-the-loop decision is always attributed. It reports whether the id was pending.

func (*Manager) RestoreSnapshot 

func (m *Manager) RestoreSnapshot(ctx context.Context, snapshotID, owner string) (*backend.Sandbox, error)

RestoreSnapshot recreates a governed sandbox from a snapshot, re-deriving policy and guardrails from the snapshot's profile.

func (*Manager) Sandbox 

func (m *Manager) Sandbox(id string) (*backend.Sandbox, bool)

Sandbox returns the handle for a sandbox id.

func (*Manager) SandboxOwner 

func (m *Manager) SandboxOwner(id string) (owner string, ok bool)

SandboxOwner returns the owning principal for a sandbox id. ok is false when the sandbox is unknown; a known-but-unowned sandbox returns ("", true).

func (*Manager) SandboxUsage 

func (m *Manager) SandboxUsage(id string) accounting.Usage

SandboxUsage returns the cumulative reported usage for a sandbox.

func (*Manager) Shell 

func (m *Manager) Shell(ctx context.Context, id string, command []string, workdir string) (*ToolResult, error)

Shell runs a command vector in the sandbox under policy control.

func (*Manager) Signed 

func (m *Manager) Signed() bool

Signed reports whether the ledger is being signed.

func (*Manager) Snapshot 

func (m *Manager) Snapshot(ctx context.Context, id, name string) (*backend.SnapshotRef, error)

Snapshot captures a sandbox's workspace and registers the reference.

func (*Manager) StateDir 

func (m *Manager) StateDir() string

StateDir returns the directory holding runeward state (ledger, keys, and terminal recordings).

func (*Manager) VerifyLedger 

func (m *Manager) VerifyLedger() error

VerifyLedger checks the hash chain and, when signing is enabled, signatures.

type ProfileInfo 

type ProfileInfo struct {
	Name   string `json:"name"`
	Host   string `json:"host"`
	Egress string `json:"egress"`
}

ProfileInfo is a lightweight profile descriptor for listing.

type SandboxInfo 

type SandboxInfo struct {
	Sandbox backend.Sandbox
	Owner   string
}

SandboxInfo pairs a sandbox handle with its owning principal for listing.

type Session 

type Session struct {
	Sandbox *backend.Sandbox
	Backend backend.Backend
	Profile *profile.Profile
	Engine  policy.Evaluator
	Guard   *policy.Guard

	Env     map[string]string
	Workdir string

	// Owner is the name of the RBAC principal that created the sandbox, used
	// for per-principal ("multi-user") visibility and access control. Empty
	// when RBAC is not configured.
	Owner string
	// contains filtered or unexported fields
}

Session is the per-sandbox governed state.

type ToolResult 

type ToolResult struct {
	Verdict    profile.Verdict `json:"verdict"`
	Reason     string          `json:"reason,omitempty"`
	ApprovalID string          `json:"approval_id,omitempty"`
	Pending    bool            `json:"pending,omitempty"`
	ExitCode   int             `json:"exit_code"`
	Stdout     string          `json:"stdout,omitempty"`
	Stderr     string          `json:"stderr,omitempty"`
	DurationMS int64           `json:"duration_ms"`
}

ToolResult is the governed outcome of a single tool invocation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.