instance

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PortRangeStart = 43000
	PortRangeEnd   = 43999
)

Variables

View Source 
var ErrNameExists = errors.New("instance name already exists")

ErrNameExists is returned when an instance name is already taken.

View Source 
var ErrNotFound = errors.New("instance not found")

ErrNotFound is returned when an instance does not exist on disk.

View Source 
var ErrRequiredField = errors.New("required field is missing")

ErrRequiredField is returned when a required field is missing.

View Source 
var ErrUnsupportedFramework = errors.New("unsupported framework")

ErrUnsupportedFramework is returned for unknown framework names.

Functions

func AllocatePort 

func AllocatePort(existing []Instance) (int, error)

AllocatePort finds the first available port in the instance range (43000-43999) that is not used by any existing instance. Known framework ports (42617, 18789, 7200) are outside this range and don't need explicit reservation. Callers must handle bind failures — the port is not held open.

func DefaultAllowedCommands 

func DefaultAllowedCommands() []string

DefaultAllowedCommands returns a copy of the default command allowlist.

Types

type CreateRequest 

type CreateRequest struct {
	Name          string        `json:"name"`
	Framework     string        `json:"framework"`
	PersonaID     string        `json:"persona_id,omitempty"`
	HierarchyRole HierarchyRole `json:"hierarchy_role,omitempty"`
	ProjectID     string        `json:"project_id,omitempty"`
	ParentID      string        `json:"parent_id,omitempty"`
	Model         string        `json:"model,omitempty"` // override persona default
	AutoStart     *bool         `json:"auto_start,omitempty"`
	CreatedBy     string        `json:"created_by,omitempty"` // "user" or parent instance ID

	// Project context — populated by the server handler (not from API body)
	// so the provisioner can include project info in identity templates.
	ProjectName        string `json:"-"`
	ProjectGoal        string `json:"-"`
	ProjectDescription string `json:"-"`
}

CreateRequest holds the parameters for provisioning a new instance.

type HierarchyRole 

type HierarchyRole string

HierarchyRole defines the role an instance plays in the agent hierarchy. 

const (
	RoleCommander  HierarchyRole = "commander"
	RoleCaptain    HierarchyRole = "captain"
	RoleTalon      HierarchyRole = "talon"
	RoleStandalone HierarchyRole = "" // not part of a hierarchy
)

func (HierarchyRole) Valid 

func (r HierarchyRole) Valid() bool

Valid returns true if r is one of the recognised hierarchy roles (including empty/standalone).

type Instance 

type Instance struct {
	ID              string         `json:"id"`
	Name            string         `json:"name"`         // slug: "strategist-sarah"
	DisplayName     string         `json:"display_name"` // "Strategist Sarah"
	Framework       string         `json:"framework"`    // "zeroclaw", "openclaw", "hermes", "picoclaw", "embedded"
	PersonaID       string         `json:"persona_id,omitempty"`
	HierarchyRole   HierarchyRole  `json:"hierarchy_role,omitempty"`
	ProjectID       string         `json:"project_id,omitempty"`
	ParentID        string         `json:"parent_id,omitempty"` // instance that created this one
	Port            int            `json:"port"`
	ConfigPath      string         `json:"config_path"`
	WorkspacePath   string         `json:"workspace_path"`
	AuthToken       string         `json:"-"` // gateway auth token — excluded from JSON output
	Status          InstanceStatus `json:"status"`
	StatusUpdatedAt time.Time      `json:"status_updated_at,omitempty"`
	PID             int            `json:"pid,omitempty"`
	LastSeen        time.Time      `json:"last_seen,omitempty"`
	HealthStatus    string         `json:"health_status,omitempty"` // "healthy", "unhealthy", "unknown"
	RestartCount    int            `json:"restart_count,omitempty"`
	CreatedAt       time.Time      `json:"created_at"`
	CreatedBy       string         `json:"created_by"` // "user" or parent instance ID
}

Instance is a named, configured agent deployment running on a specific framework. Each instance has its own config file, workspace directory, gateway port, and process.

type InstanceStatus 

type InstanceStatus string

InstanceStatus represents the lifecycle state of an instance. 

const (
	StatusCreated  InstanceStatus = "created"
	StatusStarting InstanceStatus = "starting"
	StatusRunning  InstanceStatus = "running"
	StatusStopped  InstanceStatus = "stopped"
	StatusError    InstanceStatus = "error"
)

func (InstanceStatus) Valid 

func (s InstanceStatus) Valid() bool

Valid returns true if s is a recognised instance status.

type MigrationResult 

type MigrationResult struct {
	InstanceID   string   `json:"instance_id"`
	InstanceName string   `json:"instance_name"`
	Framework    string   `json:"framework"`
	Applied      []string `json:"applied,omitempty"` // human-readable descriptions of changes
	Skipped      bool     `json:"skipped,omitempty"` // true if no changes needed
	Error        string   `json:"error,omitempty"`
}

MigrationResult reports what happened to a single instance.

func MigrateAll 

func MigrateAll() ([]MigrationResult, error)

MigrateAll applies config migrations to all provisioned instances. Each migration is idempotent — safe to run repeatedly.

type Provisioner 

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

Provisioner creates new agent instances with full workspace and config.

func NewProvisioner 

func NewProvisioner(store *Store) *Provisioner

func (*Provisioner) Provision 

func (p *Provisioner) Provision(req CreateRequest, pers *persona.Persona) (*Instance, error)

Provision creates a new agent instance: allocates a port, scaffolds the workspace directory with identity files, generates the framework config, and saves the instance metadata.

type Store 

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

Store manages instance metadata on disk at ~/.eyrie/instances/. Each instance gets its own subdirectory containing an instance.json file with the metadata.

func NewStore 

func NewStore() (*Store, error)

func (*Store) Delete 

func (s *Store) Delete(id string) error

Delete removes an instance directory and all its contents. Returns ErrNotFound if the instance does not exist.

func (*Store) Dir 

func (s *Store) Dir(id string) string

Dir returns the base directory for a given instance ID. Returns an empty string if the ID is invalid (fails path-safety validation).

func (*Store) Get 

func (s *Store) Get(id string) (*Instance, error)

Get returns a single instance by ID.

func (*Store) List 

func (s *Store) List() ([]Instance, error)

List returns all instances from disk.

func (*Store) NameExists 

func (s *Store) NameExists(name string) (bool, error)

NameExists checks whether an instance with the given name already exists.

func (*Store) Save 

func (s *Store) Save(inst Instance) error

Save writes instance metadata to disk atomically.

func (*Store) UpdateStatus 

func (s *Store) UpdateStatus(id string, status InstanceStatus) error

UpdateStatus updates just the status field for an instance. Returns an error if status is not a valid InstanceStatus.

type TemplateContext 

type TemplateContext struct {
	Name               string
	DisplayName        string
	Role               string
	Description        string
	ParentAgent        string
	EyrieURL           string
	Framework          string
	ProjectName        string // populated when instance belongs to a project
	ProjectGoal        string
	ProjectDescription string
}

TemplateContext is passed to identity file templates when rendering.

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.