remote

type Agent interface {
	// Start hands over the work and returns the stream of NDJSON lines.
	Start(ctx context.Context, req StartRequest) (io.ReadCloser, error)

	// Resume picks the same execution's stream back up after `after`.
	// It returns a GapError when its buffer no longer reaches that far.
	Resume(ctx context.Context, execID string, r Resume) (io.ReadCloser, error)

	// Cancel asks the host to stop the process. See Executor.Cancel for what
	// its error means, which is the part that matters.
	Cancel(ctx context.Context, execID string) error
}

type Executor struct {
	Agent Agent
	Host  string

	// LeaseLimit is how long the stream may go without any line -- including
	// the agent's periodic `alive` -- before the step is failed. Zero takes
	// DefaultLeaseLimit.
	LeaseLimit time.Duration

	// Retries is how many times a dropped connection is resumed before the step
	// is failed. Zero takes defaultRetries.
	//
	// It is bounded rather than endless because an agent that drops the
	// connection every second is not a network blip, and retrying forever turns
	// a broken host into a step that never ends.
	Retries int
	// contains filtered or unexported fields
}

type GapError struct {
	Wanted    int64 `json:"wanted"`
	Available int64 `json:"available"`
}

type HTTPAgent struct {
	BaseURL string
	Token   string
	Client  *http.Client
}

type Line struct {
	// Seq is monotonic from 1, per execution, and never reused. It is what
	// makes a resumed stream safe: see the package comment, decision 1.
	Seq int64 `json:"seq"`

	Kind    string `json:"kind"`
	Stream  string `json:"stream,omitempty"`
	Message string `json:"message,omitempty"`

	// Code is the process's exit status, on a KindExit line.
	Code int `json:"code,omitempty"`
}

type Resume struct {
	Protocol int    `json:"protocol"`
	After    int64  `json:"after"`
	Reason   string `json:"reason,omitempty"`
}

type StartRequest struct {
	Protocol    int    `json:"protocol"`
	ExecutionID string `json:"execution_id"`
	NodeID      string `json:"node_id"`

	// Identifying, not behavioural: they let an operator on the host see which
	// run a process belongs to, which is the whole reason the pod carries them
	// as labels.
	Workflow string `json:"workflow"`
	RunID    string `json:"run_id"`
	Attempt  int    `json:"attempt"`

	Command string            `json:"command"`
	WorkDir string            `json:"workdir,omitempty"`
	Env     map[string]string `json:"env,omitempty"`

	// Secrets is variable-name -> `secret-name/key`, UNRESOLVED, and it is the
	// point of decision 3.
	//
	// The engine does not hold these values and does not learn them. The agent
	// resolves each coordinate against its own store, under its own allowlist,
	// on the host that administers them. That is what the kubelet does for a
	// pod and what the OS does for a local process; sending resolved values
	// over mTLS instead would protect the wire and do nothing about the
	// dispatcher, the task assembly log, or any TaskExec dump somebody writes
	// later -- which is what `TaskExec.Secrets`' own comment was written about.
	//
	// An agent that cannot resolve one must FAIL the step naming the
	// coordinate. Starting a step with a variable silently unset is how a 401
	// three layers down gets blamed on the wrong service.
	Secrets map[string]string `json:"secrets,omitempty"`

	// TimeoutSeconds is zero for no limit, matching TaskExec.Timeout.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
}