hostup

package
v0.50.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package hostup is the reconcile engine behind `hadron team host up` (hadron-cli#1389, epic hadron-server#4229): compare what a host SHOULD run with what it DOES run, plan the missing steps, and, on apply, carry them out through an Actuator.

The engine is pure over three seams, so it can be driven by fakes:

Source    what should run: one Snapshot per host (the server's
          hostDesiredState once hadron-server#4222/#4224 land; a file or
          an in-memory fake until then)
Observer  what does run: registration, worktree, agent terminals
Actuator  how a planned step is carried out (the typed host-operation
          queue, cor:agt:070:05; a host-local relaunch later, cli#2060)

What it never does, whatever the seams say: act on a worker the platform marked leave-alone, halted, paused, team-paused, resetting or retired; act when the App's sweep mode is not APPLY; cast, bind, rebind or end anything; act on a worker it could not observe.

Index

Constants

View Source
const (
	Running = "RUNNING"
	Stopped = "STOPPED"
)

Desired values of Worker.Desired.

View Source
const (
	ActionWorktreeCreate = "worktree.create"
	ActionWorkerStart    = "worker.start"
	// ActionWorkerRelaunch labels skipped work in reconciliation output. The
	// CLI never plans or applies it; the periodic poller is the launch owner.
	ActionWorkerRelaunch = "worker.relaunch"
	// ActionSessionEnd labels, the same way, the end of a short-lived
	// worker's agentless session (cli#2201): the host poller proves no agent
	// runs and asks the server to end it; host up reports it, never acts.
	ActionSessionEnd = "session.end"
)

The actions a plan can hold. The first two are the typed host operations `worker onboard` issues; the third is host-local (cli#2060) and is planned only when the Actuator supports it.

View Source
const (
	// Why a step is planned (and, once done, applied).
	ReasonWorktreeMissing = "WORKTREE_MISSING"
	ReasonNoSession       = "NO_SESSION"
	ReasonTerminalMissing = "TERMINAL_MISSING"

	// Why a worker was left alone. The platform's own stop reasons
	// (LEAVE_ALONE, HALTED, PAUSED, TEAM_PAUSED, RESETTING, RETIRED,
	// SWEEP_OFF) pass through unchanged.
	ReasonInSync        = "IN_SYNC"
	ReasonSweepNotApply = "SWEEP_NOT_APPLY"
	ReasonNotOnHost     = "NOT_ON_HOST"
	ReasonNotRegistered = "NOT_REGISTERED"
	// ReasonNotAssigned: the App's setup source is SERVER and the platform
	// does not assign this worker to this host (cli#2085).
	ReasonNotAssigned            = "NOT_ASSIGNED"
	ReasonUnknownDesired         = "UNKNOWN_DESIRED"
	ReasonUnknownReason          = "UNKNOWN_REASON"
	ReasonSessionWithoutWorktree = "SESSION_WITHOUT_WORKTREE"
	ReasonTerminalWithoutSession = "TERMINAL_WITHOUT_SESSION"
	ReasonDuplicateAgents        = "DUPLICATE_AGENTS"
	ReasonNoWorktreeSource       = "NO_WORKTREE_SOURCE"
	ReasonSetupInvalid           = "SETUP_INVALID"
	ReasonRelaunchUnavailable    = "RELAUNCH_UNAVAILABLE"
	ReasonRelaunchUnproven       = "RELAUNCH_UNPROVEN"
	ReasonRelaunchPendingPoller  = "RELAUNCH_PENDING_POLLER"
	ReasonActionUnavailable      = "ACTION_UNAVAILABLE"
	ReasonStopPending            = "STOP_PENDING"
	// ReasonAgentlessSession: a SHORT_LIVED worker with no open task still has
	// an open session and no agent terminal (cli#2201).
	ReasonAgentlessSession = "AGENTLESS_SESSION"

	// Why a step failed.
	ReasonObserveFailed = "OBSERVE_FAILED"
	ReasonActionFailed  = "ACTION_FAILED"
	ReasonRefused       = "REFUSED"
	ReasonNotAttempted  = "NOT_ATTEMPTED"
)

Reason codes. They are part of the `--json` contract: add, never repurpose.

View Source
const SweepApply = "APPLY"

SweepApply is the only sweep mode under which the engine acts.

Variables

View Source
var ErrLocked = errors.New("another host up run holds this host's lock")

ErrLocked is another run holding the host's lock.

Functions

func Lock

func Lock(dir, hostID string) (func(), error)

Lock takes the per-host run lock in dir, without waiting: two applying runs on one host never overlap (a timer's sweep and a hand run, or two sweeps when one runs long), and the second leaves at once with ErrLocked rather than queueing behind the first. It is an OS file lock, so a run that dies leaves nothing stale behind. The returned func releases it.

Types

type AbortError

type AbortError struct{ Err error }

AbortError is how an Actuator says the whole run must stop: nothing further is attempted (a refused credential must not be retried per worker).

func (*AbortError) Error

func (e *AbortError) Error() string

func (*AbortError) Unwrap

func (e *AbortError) Unwrap() error

type Actuator

type Actuator interface {
	Supports(action string) bool
	Apply(ctx context.Context, w Worker, s Step) (ref string, err error)
}

Actuator carries out a step. Supports says whether it can, so a plan never holds a step that apply could not attempt. Apply returns a reference to what it did (a host-operation id), which may be set even when it fails.

type Engine

type Engine struct {
	Source   Source
	Observer Observer
	Actuator Actuator
}

Engine reconciles one host.

func (Engine) Run

func (e Engine) Run(ctx context.Context, o Options) (Result, error)

Run reads the desired state, observes, plans and (with Options.Apply) applies. The Result is complete even when the returned error is non-nil: that error is the Source's, or the AbortError that stopped an apply.

type Item

type Item struct {
	WorkerID string
	Worker   string
	// Action is the step, or for a skipped worker the step the engine did
	// not take ("" when there was none to take).
	Action string
	Reason string
	Args   map[string]string
	// Ref is the Actuator's reference for an applied or failed step.
	Ref string
	// Detail is free text for a human: the failure, or what was seen.
	Detail string
}

Item is one line of a run's result: a step planned, applied or failed, or a worker skipped.

type Observation

type Observation struct {
	// PollerConnected is an engine extension point for an in-process adapter
	// with a proven live association. The current CLI observer never sets it:
	// host up reports RELAUNCH_UNPROVEN. Metadata or a state file is not proof.
	PollerConnected bool
	// Registered: the host's registration lists this worker.
	Registered bool
	// WorktreeExists: the worker's worktree (or plain directory) is there.
	WorktreeExists bool
	// AgentTerminals: terminals conservatively counted as possible agents.
	// Unidentified terminals count unless the strict census proves them empty.
	AgentTerminals int
	// UnidentifiedTerminals: how many of AgentTerminals Orca listed with no
	// agentIdentity and not proven empty. They count as present; the item's
	// detail says when that count still includes possible leftover shells.
	UnidentifiedTerminals int
}

Observation is what the host shows for one worker.

type Observer

type Observer interface {
	Observe(ctx context.Context, w Worker) (Observation, error)
}

Observer reads the host. An error means "could not tell", and the engine then plans nothing for that worker; an *AbortError stops the whole run before anything is applied.

type Options

type Options struct {
	HostID string
	// Apply carries the plan out. False is a dry run: the Actuator's Apply is
	// never called.
	Apply bool
	// Only narrows the run to one worker, matched against a worker's id or
	// name (case-insensitively). A worker the snapshot does not hold is
	// reported as NOT_ON_HOST and nothing is created for it.
	Only string
}

Options select the run.

type Result

type Result struct {
	HostID    string
	SweepMode string
	// SetupSource echoes Snapshot.SetupSource.
	SetupSource string
	DryRun      bool
	Planned     []Item
	Applied     []Item
	Skipped     []Item
	Failed      []Item
}

Result is one run.

type Setup

type Setup struct {
	// Worktree is the worker's worktree name token, relative to the host's
	// worktrees root: "<repo's last segment>/<label>" for a git worktree, or
	// the name of a plain directory for a worker without Git.
	Worktree string
	// Repo, BaseBranch and Branch are what worktree.create needs. A worker
	// with no Repo is never given a worktree: its directory must exist.
	Repo       string
	BaseBranch string
	Branch     string
	// Family is the model family worker.start launches.
	Family string
	// RepoSource, when set, names the repos the worker's role has, read only
	// when the worktree is missing and Repo is empty. Exactly one entry is the
	// repo a worktree.create is planned from; zero, several or a failed read is
	// NO_WORKTREE_SOURCE: a repo is never guessed (cli#2085).
	RepoSource func(ctx context.Context) ([]string, error)
	// Problem, when set, is why the source could not give a usable setup
	// (no worktree, several, or a malformed value). The worker is then
	// reported SETUP_INVALID before the host is read for it.
	Problem string
}

Setup is what the host needs to start a worker.

type Snapshot

type Snapshot struct {
	HostID    string
	SweepMode string
	// SetupSource is the App's hostSetupSource ("HOST" or "SERVER") when the
	// source read it, else "" (a file, or a server that predates it).
	SetupSource string
	Workers     []Worker
}

Snapshot is a host's desired state.

type Source

type Source interface {
	DesiredState(ctx context.Context, hostID string) (Snapshot, error)
}

Source reads a host's desired state.

type Step

type Step struct {
	Action string
	Reason string
	Args   map[string]string
}

Step is one planned action for one worker.

type Worker

type Worker struct {
	WorkerID string
	Name     string
	Desired  string
	Reason   string
	// WouldBe is what Desired would read without the marker in Reason (the
	// server reports it for LEAVE_ALONE). Echoed, never acted on.
	WouldBe string
	// SessionID is the worker's open session, or "".
	SessionID string
	Setup     Setup
	// Unassigned: the App's setup source is SERVER and the platform does not
	// assign this worker to this host. Reported, never acted on (cli#2085).
	Unassigned bool
	// Absent: assigned to this host by the platform, but the desired state
	// does not list it (the host's registration does not). It has no desired
	// state to act on: reported NOT_REGISTERED, never acted on (cli#2085).
	Absent bool
}

Worker is one worker's desired state on a host.

Jump to

Keyboard shortcuts

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