node

package
v0.11.1 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Overview

Package node implements the enrolled execution service. A node can coordinate work as an orchestrator and execute requested work as a worker. These are roles within an operation, not distinct runtime types. AI agents are optional providers.

Index

Constants

View Source
const HybridSystemMetricsSeconds = 60

HybridSystemMetricsSeconds is a Hybrid System companion's default sampling interval. Grouped host displays use companion telemetry only while User is offline, so it samples less often. Explicit refreshes stay immediate.

Variables

View Source
var ErrUnregistered = errors.New("machine was unregistered by its fleet owner")

Functions

func Bridge

func Bridge(ctx context.Context, a, b net.Conn)

Bridge preserves TCP half-close when supported and joins both copy directions.

func HTTPServer

func HTTPServer(address string, handler http.Handler) *http.Server

Types

type APICall

type APICall = model.APICall

type BrowserConfig added in v0.8.2

type BrowserConfig struct {
	CLI    string `json:"cli"`
	Config string `json:"config,omitempty"`
}

BrowserConfig opts into an installed agent-browser CLI. Config optionally selects a trusted upstream configuration, not workspace auto-discovery.

type Command

type Command struct {
	Command     string            `json:"command"`
	Args        []string          `json:"args,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	Dir         string            `json:"dir,omitempty"`
	Description string            `json:"description,omitempty"`
	InputSchema json.RawMessage   `json:"inputSchema,omitempty"`
	URL         string            `json:"url,omitempty"`
}

type Config

type Config struct {
	Name    string `json:"name"`
	Gateway string `json:"gateway"`
	Token   string `json:"token,omitempty"`
	// GatewayProxy sends every gateway request through one explicit CONNECT
	// proxy, ignoring inherited proxy variables and never falling back directly.
	// Peer WebRTC traffic and provider environments are unaffected.
	GatewayProxy *model.GatewayProxy `json:"gatewayProxy,omitempty"`
	// ProxyEndpoints advertises CONNECT proxies on this host that other fleet
	// machines may use to reach the gateway: separately managed software, or
	// Control's own fixed-gateway listener when managed is set.
	ProxyEndpoints []model.ProxyEndpoint `json:"proxyEndpoints,omitempty"`
	// InstructionOnly requires an exact grant even from account clients.
	// Hybrid system profiles enable it and retain a private local API.
	InstructionOnly        bool               `json:"instructionOnly,omitempty"`
	HybridSystem           bool               `json:"hybridSystem,omitempty"`
	DataDir                string             `json:"dataDir"`
	WorkDir                string             `json:"workDir"`
	Listen                 string             `json:"listen,omitempty"`
	Labels                 map[string]string  `json:"labels,omitempty"`
	RelayOnly              bool               `json:"relayOnly,omitempty"`
	ICEServers             []webrtc.ICEServer `json:"iceServers"`
	MaxTasks               int                `json:"maxTasks,omitempty"`
	MaxOperations          int                `json:"maxOperations,omitempty"`
	MaxTaskStaging         int                `json:"maxTaskStaging,omitempty"`
	MaxTaskPublications    int                `json:"maxTaskPublications,omitempty"`
	MaxDelegationsPerOwner int                `json:"maxDelegationsPerOwner,omitempty"`
	// MetricsIntervalSeconds zero selects 15 seconds, or HybridSystemMetricsSeconds
	// for a Hybrid System companion; -1 disables periodic sampling.
	MetricsIntervalSeconds int `json:"metricsIntervalSeconds,omitempty"`
	// TaskRetentionHours keeps terminal task records, logs, and workspaces for
	// reconciliation. Zero selects 168 hours; -1 disables age-based pruning.
	TaskRetentionHours int `json:"taskRetentionHours,omitempty"`
	// MaxRetainedTasks bounds retained terminal tasks. Zero selects 10000; -1
	// disables count-based pruning.
	MaxRetainedTasks int `json:"maxRetainedTasks,omitempty"`
	// Zero preserves unlimited artifact storage; a positive value caps blobs,
	// import staging and resumable partials together. The budget never evicts
	// content; age-based expiry is ArtifactRetentionHours.
	MaxArtifactBytes int64 `json:"maxArtifactBytes,omitempty"`
	// ArtifactRetentionHours zero keeps published artifacts until explicit
	// removal; 1..87600 deletes artifacts older than that age once no retained
	// task, grant or reader still uses them.
	ArtifactRetentionHours int    `json:"artifactRetentionHours,omitempty"`
	ArtifactReserveBytes   uint64 `json:"artifactReserveBytes,omitempty"`
	PartialRetentionHours  int    `json:"partialRetentionHours,omitempty"`
	MaxUploadStagingBytes  int64  `json:"maxUploadStagingBytes,omitempty"`
	MaxUploadOwnerBytes    int64  `json:"maxUploadOwnerBytes,omitempty"`
	UploadReserveBytes     uint64 `json:"uploadReserveBytes,omitempty"`
	UploadRetentionHours   int    `json:"uploadRetentionHours,omitempty"`
	// Allow maps caller IDs, names, *, or @orchestrator to method glob patterns.
	// An omitted map permits same-fleet discovery and account-client execution.
	// An empty map denies incoming calls without a valid instruction/artifact grant.
	// Neither rules nor grants bypass fleet membership or task ownership.
	Allow     map[string][]string `json:"allow,omitempty"`
	Providers map[string]Command  `json:"providers,omitempty"`
	Agents    map[string]Command  `json:"agents,omitempty"`
	MCP       map[string]Command  `json:"mcp,omitempty"`
	// Desktop opts into worker-local agent-desktop control.
	Desktop *DesktopConfig `json:"desktop,omitempty"`
	Browser *BrowserConfig `json:"browser,omitempty"`
}

func LoadConfig

func LoadConfig(path string) (Config, error)

func (*Config) Route added in v0.9.1

func (c *Config) Route() (gatewayroute.Route, error)

Route returns this profile's gateway route.

func (*Config) UnmarshalJSON added in v0.8.0

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects the removed RPA setting instead of silently disabling desktop access in existing profiles. Other unknown settings remain tolerated.

type DesktopConfig added in v0.5.4

type DesktopConfig struct {
	Command
	Library string `json:"library,omitempty"`
	// CLI enables the complete installed agent-desktop command surface.
	// It may coexist with Library, which retains private-pipe secret input.
	CLI string `json:"cli,omitempty"`
}

DesktopConfig enables the full installed CLI and/or protected native input. An explicit external Command is retained for existing native-helper profiles.

type Execution

type Execution struct {
	Dir   string
	Log   io.Writer
	Owner string
}

type Node

type Node struct {
	Config   Config
	Identity *identity.Identity
	Peer     *transport.Peer
	// contains filtered or unexported fields
}

Node owns a machine's capabilities, tasks, artifacts, and peer connections.

func New

func New(cfg Config, peerOptions ...transport.Options) (*Node, error)

func (*Node) Call

func (n *Node) Call(ctx context.Context, target, method string, params any, result any) error

func (*Node) Capabilities

func (n *Node) Capabilities() []model.Capability

func (*Node) Close

func (n *Node) Close() error

func (*Node) ConfigureStartup added in v0.5.0

func (n *Node) ConfigureStartup(prepare func(context.Context, string) error)

ConfigureStartup is installed by the executable before Start. The handler may prepare only the running profile's migration, without scripts, paths, or UAC.

func (*Node) ConfigureUpdates

func (n *Node) ConfigureUpdates(info buildinfo.Info, apply func(string) error) error

ConfigureUpdates is called by the executable before Start. Libraries/tests cannot accidentally replace their own test runner through an update message.

func (*Node) Download

func (n *Node) Download(ctx context.Context, a model.Artifact, offset int64, dest io.Writer) (err error)

func (*Node) FollowTaskLogs

func (n *Node) FollowTaskLogs(ctx context.Context, target, id string, offset int64, emit func(model.TaskLogChunk) error) error

func (*Node) Handler

func (n *Node) Handler() http.Handler

Handler is the authenticated local API used by CLI and MCP clients. Bind it to loopback; it carries the local node's authority, not a remote caller's.

func (*Node) OpenTCP

func (n *Node) OpenTCP(ctx context.Context, target, address string) (net.Conn, error)

func (*Node) OpenTCPListener

func (n *Node) OpenTCPListener(ctx context.Context, target, listen string) (net.Conn, string, error)

OpenTCPListener keeps the local node out of maintenance while it relays a process-owned remote listener, including periods without active sockets.

func (*Node) Register

func (n *Node) Register(p Provider) error

Register must be called before Start. The same API is used by built-ins.

func (*Node) SetShutdown

func (n *Node) SetShutdown(stop func())

SetShutdown configures local service control before Start.

func (*Node) Start

func (n *Node) Start(ctx context.Context) error

func (*Node) Unregistered

func (n *Node) Unregistered() bool

Unregistered reports whether the node durably received identity retirement.

func (*Node) WaitTask

func (n *Node) WaitTask(ctx context.Context, target, id string) (model.Task, error)

type Provider

type Provider interface {
	Capability() model.Capability
	Run(context.Context, json.RawMessage, Execution) (any, error)
}

Providers share this interface whether built in or backed by a subprocess.

type WorkflowStep

type WorkflowStep = model.WorkflowStep

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL