hitl

type Actor struct {
	ID     string      `json:"id"`
	Name   string      `json:"name,omitempty"`
	Source ActorSource `json:"source"`
	KeyID  string      `json:"key_id,omitempty"`
}

type ActorSource string

type AskPayload struct {
	Question string   `json:"question"`
	Choices  []string `json:"choices,omitempty"`
}

type AskRequests struct{}

type AuditEntry struct {
	Seq            int64      `json:"seq"`
	Event          AuditEvent `json:"event"`
	InterventionID string     `json:"intervention_id,omitempty"`
	EnvID          string     `json:"env_id,omitempty"`
	Actor          Actor      `json:"actor"`
	RemoteAddr     string     `json:"remote_addr,omitempty"`
	// RecordingID links a takeover session's encrypted cast. empty for
	// every other event.
	RecordingID string    `json:"recording_id,omitempty"`
	At          time.Time `json:"at"`
	PrevHash    []byte    `json:"prev_hash"`
	Hash        []byte    `json:"hash"`
}

type AuditEvent string

type ChainError struct {
	Seq    int64
	Reason string
}

type ComputerCall struct {
	Action string
	Text   string
}

type ComputerPayload struct {
	Action string          `json:"action"`
	Text   string          `json:"text,omitempty"`
	Input  json.RawMessage `json:"input"`
}

type ComputerResult struct {
	Output     string `json:"output,omitempty"`
	Screenshot string `json:"screenshot,omitempty"`
}

type Credential struct {
	Master bool
	KeyID  string
	// Label is the key's label, recorded as the name of a key actor.
	Label string
	// Pinned is the actor fixed on the key, nil when none.
	Pinned *Actor
	// ActAs reports whether the key holds hitl:act-as.
	ActAs bool
}

type Decider struct {
	URL    string `json:"url"`
	Secret string `json:"secret"`
}

type DeciderLifecycle struct {
	Action LifecycleAction `json:"action"`
	Params json.RawMessage `json:"params,omitempty"`
}

type DeciderNote struct {
	Verdict DeciderVerdict `json:"verdict"`
	Reason  string         `json:"reason,omitempty"`
	// Error is set when the call failed and fuse fell through to ask.
	Error string `json:"error,omitempty"`
}

type DeciderRequest struct {
	EnvID       string            `json:"env_id"`
	Gate        string            `json:"gate"`
	On          Kind              `json:"on"`
	TriggeredBy Actor             `json:"triggered_by"`
	Exec        *ExecPayload      `json:"exec,omitempty"`
	Lifecycle   *DeciderLifecycle `json:"lifecycle,omitempty"`
	Computer    *ComputerPayload  `json:"computer,omitempty"`
	// Screenshot is a base64 png of the display, for a computer action. it
	// is empty when one could not be taken in time.
	Screenshot string    `json:"screenshot,omitempty"`
	Deadline   time.Time `json:"deadline"`
}

type DeciderResponse struct {
	Decision DeciderVerdict `json:"decision"`
	// Reason goes back to the agent on a deny, and to the human on an ask.
	Reason string `json:"reason,omitempty"`
}

type DeciderVerdict string

type Decision struct {
	Outcome Outcome
	// Answer is the human's reply to an ask. empty unless approved.
	Answer string
	// Reason is text fed back to the agent. always set on a reject.
	Reason    string
	DecidedBy Actor
	DecidedAt time.Time
	// EditedArgv replaces a held exec's argv, set when the human edited it.
	EditedArgv []string
	// EditedText replaces a held type action's text.
	EditedText *string
	// Grant is how far the approval reaches: once, env or ttl:<duration>.
	Grant string
}

type ErrResolved struct {
	ID    string
	State State
}

type ExecCall struct {
	// Argv is what the guest would run. a shell exec is ["sh", "-lc", script].
	Argv []string
	// Shell is true when the caller sent an opaque shell string.
	Shell bool
}

type ExecPayload struct {
	Argv []string `json:"argv"`
	// Shell is the script when the caller sent shell:, in which case Argv
	// is the sh -lc that runs it.
	Shell     string `json:"shell,omitempty"`
	TimeoutMS int64  `json:"timeout_ms,omitempty"`
}

type ExecPolicy struct {
	// Default is ask or deny.
	Default Mode `json:"default"`
	// Allow lists program basenames that run without a gate.
	Allow []string `json:"allow"`
}

type ExecResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
}

type Gate struct {
	// Name identifies the gate on interventions and grants.
	Name string `json:"name"`
	// On is the surface: exec or lifecycle.
	On Kind `json:"on"`
	// Match selects the actions the gate holds.
	Match GateMatch `json:"match"`
	// Mode is ask (the default), notify or deny.
	Mode Mode `json:"mode,omitempty"`
	// Grant is the default grant an approval creates: once (the default),
	// env, or ttl:<duration>. only meaningful for ask.
	Grant string `json:"grant,omitempty"`
	// TimeoutSeconds overrides the spec's deadline for this gate.
	TimeoutSeconds int64 `json:"timeout_seconds,omitempty"`
	// Reason is the text a deny returns, and is shown to the human on ask.
	Reason string `json:"reason,omitempty"`
	// Decide is a webhook asked before a human: it answers allow, deny or
	// ask. only for an ask gate on exec, lifecycle or computer.
	Decide *Decider `json:"decide,omitempty"`
}

type GateMatch struct {
	// Program matches the basename of argv[0] after known wrappers are
	// stripped, against any entry of the list.
	Program []string `json:"program,omitempty"`
	// Args matches when they appear in argv[1:] in order, not
	// necessarily next to each other.
	Args []string `json:"args,omitempty"`
	// Shell matches any opaque shell exec.
	Shell bool `json:"shell,omitempty"`
	// Action matches lifecycle actions (on: lifecycle) or fused's computer
	// actions (on: computer).
	Action []string `json:"action,omitempty"`
	// TextContains matches a computer type action whose text contains any
	// entry, ignoring case.
	TextContains []string `json:"text_contains,omitempty"`
	// Failures fires a stall after this many consecutive non-zero exec
	// exits.
	Failures int `json:"failures,omitempty"`
	// QuietSeconds fires a stall after this long with no exec or computer
	// call.
	QuietSeconds int64 `json:"quiet_seconds,omitempty"`
	// BeforeSeconds fires an expiry this long ahead of the idle_timeout or
	// max_runtime reap.
	BeforeSeconds int64 `json:"before_seconds,omitempty"`
}

type Grant struct {
	ID    string
	EnvID string
	Gate  string
	// Key identifies the action, see GrantKey. it never holds the argv.
	Key            string
	Scope          GrantScope
	InterventionID string
	ExpiresAt      *time.Time
	CreatedAt      time.Time
}

type GrantScope string

type GrantSpec struct {
	Scope GrantScope
	TTL   time.Duration
}

type Intervention struct {
	ID    string
	EnvID string
	Kind  Kind
	State State
	// Gate names the gate that raised it; empty for a request.
	Gate string
	// Mode is the gate's mode; empty for a request.
	Mode Mode
	// Payload is the ask, for KindAsk.
	Payload AskPayload
	// Exec is the held exec, for KindExec.
	Exec *ExecPayload
	// Lifecycle is the held environment action, for KindLifecycle.
	Lifecycle *LifecyclePayload
	// Computer is the held computer action, for KindComputer.
	Computer *ComputerPayload
	// Secret, Takeover and Review are the payloads of those kinds; nil
	// otherwise.
	Secret   *SecretPayload
	Takeover *TakeoverPayload
	Review   *ReviewPayload
	// Decider is what the gate's decider said when it sent the action on
	// to a human, nil when the gate has none or it decided on its own.
	Decider *DeciderNote
	// Signal is what fuse saw, for KindStall and KindExpiry.
	Signal      *SignalPayload
	TriggeredBy Actor
	Deadline    time.Time
	OnTimeout   OnTimeout
	Decision    *Decision
	// Result is what the orchestrator got running the approved action.
	Result    *Result
	CreatedAt time.Time
	UpdatedAt time.Time
}

type Kind string

type LifecycleAction string

type LifecyclePayload struct {
	Action LifecycleAction `json:"action"`
	Params []byte          `json:"params,omitempty"`
}

type Mode string

type Notification struct {
	Event          AuditEvent `json:"event"`
	InterventionID string     `json:"intervention_id,omitempty"`
	EnvID          string     `json:"env_id"`
	Gate           string     `json:"gate"`
	On             string     `json:"on"`
	Deadline       *time.Time `json:"deadline,omitempty"`
	URL            string     `json:"url,omitempty"`
}

type OnTimeout string

type Outcome string

type Reaper string

type Requests struct {
	Ask      *AskRequests      `json:"ask,omitempty"`
	Secret   *SecretRequests   `json:"secret,omitempty"`
	Takeover *TakeoverRequests `json:"takeover,omitempty"`
	Review   *ReviewRequests   `json:"review,omitempty"`
}

type Result struct {
	// Exec is set for an exec that ran.
	Exec *ExecResult `json:"exec,omitempty"`
	// Computer is set for a computer action that ran.
	Computer *ComputerResult `json:"computer,omitempty"`
	// EnvID is the environment a fork or migrate produced.
	EnvID string `json:"env_id,omitempty"`
	// SnapshotID is the snapshot a snapshot action produced.
	SnapshotID string `json:"snapshot_id,omitempty"`
	// Error is set when the approved action could not be performed.
	Error      string    `json:"error,omitempty"`
	FinishedAt time.Time `json:"finished_at"`
}

type ReviewFormat string

type ReviewPayload struct {
	Path    string       `json:"path,omitempty"`
	Content string       `json:"content"`
	Format  ReviewFormat `json:"format"`
	Message string       `json:"message,omitempty"`
	// Truncated is set when a file was longer than MaxReviewBytes.
	Truncated bool `json:"truncated,omitempty"`
}

type ReviewRequests struct{}

type Scope string

type SecretPayload struct {
	Target  string `json:"target"`
	Label   string `json:"label"`
	Message string `json:"message,omitempty"`
}

type SecretRequests struct {
	Targets []SecretTarget `json:"targets"`
}

type SecretTarget struct {
	Env   string `json:"env,omitempty"`
	File  string `json:"file,omitempty"`
	Label string `json:"label"`
}

type SignalPayload struct {
	// Failures is the run of consecutive non-zero exec exits (stall).
	Failures int `json:"failures,omitempty"`
	// LastExitCode is the exit code that completed the run (stall).
	LastExitCode int `json:"last_exit_code,omitempty"`
	// QuietSeconds is how long the agent made no exec or computer call
	// (stall).
	QuietSeconds int64 `json:"quiet_seconds,omitempty"`
	// Reaper and ReapAt say what will tear the environment down, and when
	// (expiry).
	Reaper Reaper     `json:"reaper,omitempty"`
	ReapAt *time.Time `json:"reap_at,omitempty"`
	// ExtendedUntil is set when a human approved an expiry: the reaper
	// leaves the environment alone until then.
	ExtendedUntil *time.Time `json:"extended_until,omitempty"`
}

type Spec struct {
	// TimeoutSeconds is the default deadline for every intervention. zero
	// means DefaultTimeout.
	TimeoutSeconds int64 `json:"timeout_seconds,omitempty"`
	// OnTimeout is how an expired intervention resolves. empty means reject.
	OnTimeout OnTimeout `json:"on_timeout,omitempty"`
	// Requests are the request kinds the agent may raise.
	Requests Requests `json:"requests"`
	// RequireActor refuses decisions that do not carry a pinned or asserted
	// actor, so every approval is tied to a named person.
	RequireActor bool `json:"require_actor,omitempty"`
	// Notify are webhooks told about every intervention and audit event.
	Notify []Webhook `json:"notify,omitempty"`
	// Gates are the enforced exec, lifecycle, computer and signal gates.
	Gates []Gate `json:"gates,omitempty"`
	// Exec is allowlist mode for exec, nil when off.
	Exec *ExecPolicy `json:"exec,omitempty"`
}

type State string

type TakeoverPayload struct {
	Via       TakeoverVia `json:"via"`
	Reason    string      `json:"reason,omitempty"`
	Holder    *Actor      `json:"holder,omitempty"`
	StartedAt *time.Time  `json:"started_at,omitempty"`
}

type TakeoverRequests struct {
	Via []TakeoverVia `json:"via,omitempty"`
}

type TakeoverVia string

type Verdict struct {
	// Deny is the first matching deny gate, nil when none matched.
	Deny *Gate
	// Ask are the matching ask gates, in declaration order.
	Ask []Gate
	// Notify are the matching notify gates, in declaration order.
	Notify []Gate
}

type Webhook struct {
	URL    string `json:"url"`
	Secret string `json:"secret"`
}