runtime

type EventType string

type Run interface {
	ID() string
	// Stream returns the event channel; it is closed when the run terminates.
	Stream() <-chan RunEvent
	// Signal injects input into a running interactive task (HITL).
	Signal(input string) error
	// Cancel terminates the run.
	Cancel() error
	// Status returns the current status.
	Status() Status
	// Wait blocks until the run terminates and returns the terminal status.
	Wait() Status
}

type RunEvent struct {
	RunID string    `json:"run_id"`
	Type  EventType `json:"type"`
	Time  time.Time `json:"time"`
	Data  string    `json:"data,omitempty"`
	Code  int       `json:"code,omitempty"` // exit code for EventExited
}

type RunSpec struct {
	RunID   string   // caller-assigned id, echoed back on the Run
	Agent   string   // provider key: claude | codex | openclaw | hermes
	Prompt  string   // the task body handed to the CLI
	Workdir string   // scoped working directory
	Env     []string // additional KEY=VALUE pairs
	// Machine is the resolved target host (spec 022). Empty means "here": the
	// local runtime handles it. A non-local name routes the spec to that
	// machine's runtime (exec/cluster). Providers ignore this field.
	Machine string
}

type Runtime interface {
	// Dispatch launches spec and returns a Run handle. The returned Run begins
	// streaming immediately; the caller drains Stream() and/or calls Wait().
	Dispatch(ctx context.Context, spec RunSpec) (Run, error)
	// Name identifies the runtime implementation (for diagnostics).
	Name() string
}

type State string

type Status struct {
	State    State  `json:"state"`
	ExitCode int    `json:"exit_code"`
	Err      string `json:"err,omitempty"`
}