runner

type CommandRunner struct{ Cmd policy.Command }

type Detection struct {
	Found        bool   `json:"found"`
	Version      string `json:"version,omitempty"`      // ynh's own version
	Capabilities string `json:"capabilities,omitempty"` // the capabilities version ynf checks abilities against
	Detail       string `json:"detail,omitempty"`       // why it was not detected
	// Features are the names ynh lists in `features`; absent means none. They are gated on by
	// name, never by comparing versions (ADR-012).
	Features []string `json:"features,omitempty"`
}

type Focus struct {
	Prompt  string `json:"prompt"`
	Profile string `json:"profile"`
}

type Harness struct {
	// ID is the installed harness's id, when it was read from an installed ynh (an image's).
	ID      string           `json:"-"`
	Focuses map[string]Focus `json:"focuses"`
	// EnvPassthrough is every variable ynh lets reach the agent worker. ynh strips everything
	// else, deliberately, model credentials and proxy settings included.
	EnvPassthrough []string `json:"env_passthrough"`
	// Agent is the harness's own budgets, which a lane may only tighten (ADR-006).
	Agent struct {
		MaxTurns  int    `json:"max_turns"`
		MaxTokens int    `json:"max_tokens"`
		MaxWall   string `json:"max_wall"`
	} `json:"agent"`
	// Sensors are the sensors the harness declares, by name; a lane may only scope these.
	Sensors map[string]json.RawMessage `json:"sensors"`
}

type HarnessSource struct {
	Dir string
	Pin *policy.Pin
}

type Installed struct {
	// ID is what `ynh agent run --harness` takes for it.
	ID      string
	Name    string
	Version string
	// Commit is the commit it was installed from; empty for a folder, which has none.
	Commit string
	// Pin is the repository and ref it was installed from, for a pin; empty for a folder.
	Pin string
	// PinURL is Pin with the repository as ynh was given it (a bare host and path made
	// https://host/path); empty for a folder.
	PinURL string
	// Path is where ynh keeps the installed harness, which holds its manifest.
	Path string
}

type Resolved struct {
	Runner Runner
	// Detected is true when the lane named no runner and detection chose this one.
	Detected bool
	// Note says what an unnamed lane resolved to on this host, such as "ynh (detected 0.10.0)" or
	// "command (ynh not found)"; empty when the lane named its runner.
	Note string
}

type Result struct {
	Outcome string `json:"outcome"`
	Detail  string `json:"detail,omitempty"`
	Model   string `json:"model,omitempty"`   // backend/model, when the runner reports one
	Session string `json:"session,omitempty"` // runner session id (ynh: session_id)
	Usage
}

type Runner interface {
	Name() string
	// Command returns the argv to run inside the worktree.
	Command(spec Spec) ([]string, error)
	// Interpret maps an exit code (and anything the run wrote to hostRunDir) to a Result.
	Interpret(exitCode int, stdout []byte, hostRunDir string) Result
}

type Spec struct {
	Lane     policy.Lane
	Labels   []string
	Task     string // the task text, written to TaskFile by the engine
	TaskFile string // path inside the worktree's step folder, as the command sees it
	RunDir   string // the step folder, as the command sees it
	Feedback string
	// InImage is set when the run happens in an image built by `ynh image --entrypoint agent`,
	// whose entrypoint is already `ynh agent run --harness local/<name>`.
	InImage bool
	// Contained is set when the run is contained (ADR-007): in an image, or inline in a container
	// the operator provides.
	Contained bool
	// Focus is the lane's focus, resolved from the harness: its prompt is already in the task.
	Focus *Focus
	// HostAutoApprove is --auto-approve asked for by the person who started the work, for a run on
	// their own machine (ADR-007). A lane's setting never applies outside containment.
	HostAutoApprove string
}

type Usage struct {
	Effort string `json:"effort,omitempty"` // reasoning effort, when the runner reports it
	// EffortRequested is the effort the run was asked for, when it was: a lane's effort or the
	// harness's default. A backend may run at another, which Effort then shows.
	EffortRequested string `json:"effort_requested,omitempty"`
	Turns           int    `json:"turns,omitempty"`  // agent turns
	Tokens          int    `json:"tokens,omitempty"` // tokens consumed: input and output
	// The split, when the runner reports it. Cache reads are not in Tokens, and are often most of
	// what a long session costs.
	InputTokens     int `json:"input_tokens,omitempty"`
	OutputTokens    int `json:"output_tokens,omitempty"`
	CacheReadTokens int `json:"cache_read_tokens,omitempty"`
	// Backend is the vendor CLI that ran, such as claude: what is known when the model is not.
	Backend string  `json:"backend,omitempty"`
	CostUSD float64 `json:"cost_usd,omitempty"` // when the runner reports it; ynf never prices tokens
	BoundBy string  `json:"bound_by,omitempty"` // the cap that ended the run, if one did
	// Harness is name@version, and HarnessSHA the commit it was installed from: a harness change is
	// a confounder when comparing models, not a model effect.
	Harness       string `json:"harness,omitempty"`
	HarnessSHA    string `json:"harness_sha,omitempty"`
	RunnerVersion string `json:"runner_version,omitempty"` // ynh's version
	// FailedSensors names the sensors that had failed when the run ended, in the runner's order.
	FailedSensors []string `json:"failed_sensors,omitempty"`
	AutoApprove   string   `json:"auto_approve,omitempty"`
}

type YnhRunner struct{ Cfg policy.Ynh }