harness

type AllowRequired struct {
	// Why is init's reason for asking.
	Why string `yaml:"why"`
	// Advice is the line init adds when it sets the harness up without the rule.
	Advice string `yaml:"advice"`
	// Missing is what init's overview says without the rule.
	Missing string `yaml:"missing"`
	// Allowed and NotAllowed are what doctor says with and without it.
	Allowed    string `yaml:"allowed"`
	NotAllowed string `yaml:"not_allowed"`
}

type Call struct {
	Op Op
	// Wake is true for a prompt that is the harness handing back the bundle a waiting
	// hook woke the session with: that prompt is the wake itself, not a later event.
	Wake bool
}

type Check struct {
	Run      []string `yaml:"run"`
	JSONTrue string   `yaml:"json_true"`
}

type CheckResult struct {
	Name, Level, Code, Message, Fix string
}

type Env struct {
	// Getenv reads an environment variable.
	Getenv func(string) string
	// Dir is the working directory, the project of a project setup.
	Dir string
	// Aboard is the aboard binary that hooks and installed files run, by absolute path,
	// and AboardHome the ABOARD_HOME aboard runs with, or "".
	Aboard, AboardHome string
}

type FallbackSpec struct {
	Event string `yaml:"event"`
	Since string `yaml:"since"`
}

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

type Handler struct {
	Type    string
	Command string
	// Timeout is in seconds; 0 leaves it out.
	Timeout int
	// Options are more settings in the harness's own words, written after the timeout.
	Options map[string]any
}

type Harness interface {
	// Profile is the harness's profile.
	Profile() *Profile
	// Detected reports whether the harness looks installed on this machine.
	Detected(e Env) bool
	// ConfigDir is the folder the harness reads its global config from.
	ConfigDir(e Env) string
	// Version is what the harness reports as its version, or "" when no hook depends
	// on it or it can't be told.
	Version(ctx context.Context, e Env) string
	// Hooks are the hook entries aboard init installs for a harness that reports
	// version, each running exe. A version that can't be read gets what the oldest
	// version Aboard works with runs; Newest gets every hook.
	Hooks(exe, version string) []Hook
	// Unsupported are the profile's hooks that Hooks leaves out for version, because
	// that version runs neither them nor a fallback.
	Unsupported(version string) []HookSpec
	// Items are what aboard init installs in a scope, in order, with their paths.
	Items(e Env, scope string) []Item
	// InstalledChecks are aboard doctor's checks that the harness is there and can be
	// delivered to. installed is false when doctor checks nothing more of it.
	InstalledChecks(ctx context.Context, e Env) (checks []CheckResult, installed bool)
	// HookCall says what "aboard hook <harness> <event>" does with the hook's input.
	HookCall(event string, in HookInput) (Call, bool)
	// Fix says how to fix a delivery that stopped for a reason this harness's
	// adapter gave, or "".
	Fix(reason string) string
	// Adapter is the delivery daemon's adapter for the harness, or nil when it has no
	// automatic delivery.
	Adapter(clientVersion string) delivery.Adapter
}

type Headless struct {
	Via          string   `yaml:"via"`
	Run          []string `yaml:"run"`
	Resume       []string `yaml:"resume"`
	SessionField string   `yaml:"session_field"`
	Model        []string `yaml:"model"`
}

type Hook struct {
	// Event is the harness's name for the hook event.
	Event string
	// Arg is the event argument of "aboard hook <harness> <arg>".
	Arg string
	// Matcher is the matcher of the hook's group, such as Bash, or "" for none.
	Matcher string
	Handler Handler
}

type HookInput struct {
	SessionID string `json:"session_id"`
	Source    string `json:"source"`
	// AgentID is set when a hook fires inside a subagent.
	AgentID string `json:"agent_id"`
	// HookEventName is the event the harness ran the hook for; a tool hook's output
	// names it back.
	HookEventName string `json:"hook_event_name"`
	// Prompt is the prompt text, on a prompt hook.
	Prompt string `json:"prompt"`
	// ToolInput is the input of the tool about to run, on a pre-tool hook. For a shell
	// command it holds the command and the tool's other settings.
	ToolInput json.RawMessage `json:"tool_input"`
}

type HookSpec struct {
	Event   string         `yaml:"event"`
	Run     string         `yaml:"run"`
	Op      Op             `yaml:"op"`
	Matcher string         `yaml:"matcher"`
	Timeout int            `yaml:"timeout"`
	Options map[string]any `yaml:"options"`
	// Since is the first version of the harness that runs the hook as written: it knows
	// the event, and honors its options and the output the hook gives.
	Since string `yaml:"since"`
	// Fallback are the events that run the same command on a version older than Since.
	Fallback []FallbackSpec `yaml:"fallback"`
	// Without is what the person loses on a version that runs neither the hook nor a
	// fallback, such as "idle sessions don't wake for new messages".
	Without string `yaml:"without"`
}

type HooksMissing struct {
	Level  string `yaml:"level"`
	Effect string `yaml:"effect"`
}

type InstallSpec struct {
	Kind        ItemKind       `yaml:"kind"`
	Global      string         `yaml:"global"`
	Project     string         `yaml:"project"`
	Format      string         `yaml:"format"`
	Source      string         `yaml:"source"`
	Rule        string         `yaml:"rule"`
	Accepts     []string       `yaml:"accepts"`
	Note        string         `yaml:"note"`
	Required    *AllowRequired `yaml:"required"`
	Missing     *HooksMissing  `yaml:"missing"`
	Text        string         `yaml:"text"`
	ProjectText string         `yaml:"project_text"`
}

type Interactive struct {
	Start  []string `yaml:"start"`
	Resume []string `yaml:"resume"`
	Model  []string `yaml:"model"`
	// Launch is where swarm up puts a new session's identity: LaunchEnv (the default)
	// or LaunchPrompt.
	Launch string `yaml:"launch"`
}

type Item struct {
	InstallSpec
	// Path is where it goes in this scope. An allow rule without a path goes in the
	// hooks file; a consent step has none.
	Path string
	// Data is what Aboard writes to a file it owns: the skill, a file, or the file
	// holding an allow rule.
	Data []byte
}

type ItemKind string

type Op string

type Profile struct {
	Harness   string `yaml:"harness"`
	Name      string `yaml:"name"`
	Command   string `yaml:"command"`
	CheckName string `yaml:"check_name"`
	Checks    struct {
		Installed Check `yaml:"installed"`
		LoggedIn  Check `yaml:"logged_in"`
		// MinVersion is the oldest version Aboard works with. A harness whose version
		// can't be read gets the hooks this version runs.
		MinVersion string `yaml:"min_version"`
	} `yaml:"checks"`
	SandboxEnv        []string `yaml:"sandbox_env"`
	SandboxNetworkEnv []string `yaml:"sandbox_network_env"`
	SandboxFix        string   `yaml:"sandbox_fix"`
	SessionEnv        []string `yaml:"session_env"`
	ConfigDir         struct {
		Env     string `yaml:"env"`
		Default string `yaml:"default"`
	} `yaml:"config_dir"`
	Install     []InstallSpec `yaml:"install"`
	Interactive Interactive   `yaml:"interactive"`
	Headless    Headless      `yaml:"headless"`
	Identity    struct {
		Kind       string   `yaml:"kind"`
		Env        string   `yaml:"env"`
		RootEnv    string   `yaml:"root_env"`
		EnvFile    string   `yaml:"env_file"`
		Precedence int      `yaml:"precedence"`
		YieldsTo   []string `yaml:"yields_to"`
	} `yaml:"identity"`
	// SubagentIdentity is whether a subagent's commands can be told from its parent's:
	// none, marked or seats.
	SubagentIdentity string `yaml:"subagent_identity"`
	Lifecycle        struct {
		Liveness         string `yaml:"liveness"`
		OutlivesTerminal bool   `yaml:"outlives_terminal"`
		ResumeKeepsID    bool   `yaml:"resume_keeps_id"`
		ResumeStart      string `yaml:"resume_start"`
		SubagentField    string `yaml:"subagent_field"`
	} `yaml:"lifecycle"`
	Delivery struct {
		Method       string     `yaml:"method"`
		Capabilities []string   `yaml:"capabilities"`
		Queue        []string   `yaml:"queue"`
		Hooks        []HookSpec `yaml:"hooks"`
		MidTurn      string     `yaml:"mid_turn"`
		// WaitingNotice is true when the tool hook also names the other waiting messages.
		WaitingNotice bool `yaml:"waiting_notice"`
	} `yaml:"delivery"`
}

type Set []Harness