executor

type Agent interface {
	UUID() uuid.UUID
	Runtime() *Runtime
	Prepare(ctx context.Context) error
	Run(ctx context.Context) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Remove(ctx context.Context) error

	// StatusTracker exposes the underlying tracker so the daemon
	// supervisor can drive transitions it owns (Ready after the
	// readiness probe answers, Working ↔ Ready around in-flight RPCs,
	// Failed+FailureReadinessTimeout on probe timeout, Failed+
	// FailureCrashed on unexpected exit). Executors mutate their own
	// status through this same tracker for the Pulling / Starting /
	// Stopped / Failed transitions they own.
	StatusTracker() *StatusTracker

	// Probe issues a single readiness check against the running
	// runtime. Returns nil when the runtime answered Ready=true.
	// Returns a non-nil error when the dial fails, the call returns
	// Unavailable, or ctx expires.
	//
	// Used by the daemon supervisor to gate the Starting → Ready
	// transition. Implementations should not retry internally — the
	// caller owns the backoff and the overall timeout.
	Probe(ctx context.Context) error

	// Exec runs a BIN command in this agent's spawn env: same image,
	// same BIN namespace on PATH, agent workspace as cwd. Implementations
	// MUST cleanly terminate the underlying execution when ctx is
	// cancelled — no orphaned processes / no zombie containers.
	// Returns when the underlying execution exits or is killed.
	//
	// `bin` is a name (e.g. "sh", "jq") resolved via PATH inside the
	// spawn env, NOT a host filesystem path. Unknown names surface as
	// ExecResult.Err so the caller can distinguish "BIN not declared in
	// the agent's image" from "BIN ran and exited non-zero."
	Exec(ctx context.Context, bin string, args []string, stdin string) ExecResult

	StatusObserver
}

type Capability = spec.Capability

type ContextEntry struct {
	Name        string `yaml:"name" json:"name"`
	File        string `yaml:"file" json:"file"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
}

type EnvOptions struct {
	// AgentRoot is the path the agent considers its root — the
	// directory under which HOME, TMPDIR, etc. live. For system
	// it's the host-side materialised tree path; for docker it's
	// the container-internal "/workspace".
	AgentRoot string

	// BinDirs are joined with ":" to form $PATH. For system
	// there is one entry (<AgentRoot>/usr/bin); for docker there
	// is one entry per BIN image mount.
	BinDirs []string

	// DaemonURL is the openotters daemon's TCP endpoint
	// (e.g. http://host.docker.internal:5050) the runtime should
	// dial back to for daemon-side capabilities (async-jobs RPCs in
	// the next iteration). Optional — empty means the spawned
	// runtime gets no OTTERSD_URL and any daemon client lazy-init
	// no-ops gracefully.
	DaemonURL string

	// AgentToken is the JWT minted by the daemon at CreateAgent. The
	// runtime presents it as `Authorization: Bearer …` on every
	// outbound RPC to DaemonURL. Issued and revoked by the daemon
	// (see internal/auth on the openotters side). Optional — empty
	// means no token is exposed and outbound RPCs would fail
	// Unauthenticated, but the agent process still spawns fine.
	AgentToken string
}

type ExecResult struct {
	Stdout, Stderr string
	ExitCode       int

	// Err is set for spawn failures (BIN not in PATH inside the
	// sandbox, container gone, sandbox unavailable) and for
	// ctx-cancellation (ctx.Err() flows through). Nil when the BIN
	// ran to completion, regardless of its exit code.
	Err error

	// Handle is a backend-specific identifier the daemon uses for
	// boot-time ghost cleanup: a PID for the system backend, a
	// container ID for docker. Empty when the spawn never happened.
	Handle string
}

type ExecStreamSinks struct {
	Stdout io.Writer
	Stderr io.Writer
}

type FailureReason uint8

type ImageInfo struct {
	Ref         string
	Digest      string
	MediaType   string // OCI artifactType from the manifest, or the Docker config media type
	Size        int64
	CreatedUnix int64
	Description string
	Source      string

	// Labels are OCI image-config labels (Dockerfile LABEL
	// directives or oras-side equivalents). Populated when the
	// backend can read them cheaply; may be empty.
	Labels map[string]string

	// Annotations are manifest-level annotations. Same population
	// caveat.
	Annotations map[string]string
}

type Mount struct {
	Host        string
	Target      string
	Description string
	ReadOnly    bool
}

type OCIRef struct {
	Ref    string `yaml:"ref" json:"ref"`
	Digest string `yaml:"digest,omitempty" json:"digest,omitempty"`
}

type ObjectPromptRequest struct {
	Prompt            string
	Schema            []byte
	SchemaName        string
	SchemaDescription string
}

type ObjectPrompter interface {
	PromptObject(ctx context.Context, req ObjectPromptRequest) ([]byte, error)
}

type PromptEvent struct {
	Type    string
	Step    int32
	Tool    string
	Content string
}

type PromptRequest struct {
	SessionID string
	Prompt    string
	// Regenerate signals the runtime to attach the produced parts
	// as a new branch onto the most recent assistant turn for
	// SessionID instead of inserting a fresh row.
	Regenerate bool
}

type Prompter interface {
	Prompt(ctx context.Context, req PromptRequest, w io.Writer) error
}

type Provider interface {
	// Create materializes and prepares an agent with the given ID, returning it ready to Run.
	Create(ctx context.Context, id uuid.UUID, ref spec.Reference, opts ...spec.Override) (Agent, error)

	// Load recovers previously created agents from the backend.
	Load(ctx context.Context) ([]Agent, error)

	// Destroy removes all agents and associated artifacts.
	Destroy(ctx context.Context) error

	// Registry returns the OCI artifact storage backend this
	// Provider is bound to. Never nil; backends that don't yet
	// support every Registry method return ErrNotImplemented.
	Registry() Registry
}

type Registry interface {
	// List enumerates all refs known to this registry. Order is
	// implementation-defined.
	List(ctx context.Context) ([]string, error)

	// ListEntries returns one ImageInfo per ref in a single backend
	// call. Implementations are free to populate every field from
	// the bulk-list response (docker's cli.ImageList already
	// includes Id, Created, Size, Labels — Inspect-per-ref would
	// re-fetch the same data) so the daemon's ListImages doesn't
	// have to fan out N additional Inspect calls.
	//
	// Returns the same ref set as List, but with metadata
	// populated. ListEntries SHOULD be the path callers prefer for
	// listing surfaces; List is kept for callers that only need the
	// ref strings (e.g. cache-warming, cleanup).
	ListEntries(ctx context.Context) ([]ImageInfo, error)

	// Resolve returns the descriptor for ref, or an error if ref
	// is not known. Errors are typed where possible
	// (errors.Is(err, ErrRefNotFound) == true on miss).
	Resolve(ctx context.Context, ref string) (ocispec.Descriptor, error)

	// Inspect returns metadata for ref: digest, size, labels,
	// annotations. Implementations populate as much as their
	// backend exposes; missing fields are zero-valued.
	Inspect(ctx context.Context, ref string) (ImageInfo, error)

	// Fetch returns a stream of the content addressed by desc.
	// Caller closes.
	Fetch(ctx context.Context, desc ocispec.Descriptor) (io.ReadCloser, error)

	// Tag points dst at the same descriptor as src. dst must be a
	// valid registry ref; src must already exist.
	Tag(ctx context.Context, src, dst string) error

	// Remove deletes ref. Unreferenced content blobs are garbage
	// collected by the backend on its own schedule.
	Remove(ctx context.Context, ref string) error

	// PullRemote fetches remoteRef from a remote registry into
	// this Registry. The local ref name matches remoteRef
	// verbatim (callers retag via Tag if they want a different
	// local name).
	PullRemote(ctx context.Context, remoteRef string) error

	// PushRemote sends localRef to a remote registry as
	// remoteRef. Auth comes from environment / credentials store
	// per backend.
	PushRemote(ctx context.Context, localRef, remoteRef string) error

	// BuildTarget exposes the underlying oras.Target for the
	// agentfile/build pipeline (which writes blobs + tags
	// directly via oras). Returns nil when the backend doesn't
	// support direct OCI writes — Docker today, until we wire
	// build-via-ImageLoad. Daemon callers must check for nil and
	// emit a clear "build unsupported on this executor" error.
	BuildTarget() oras.Target

	// ManifestKind returns the manifest's `artifactType` for ref —
	// the openotters kind ("application/vnd.openotters.{agent,bin}.v1")
	// when the producer stamped it, otherwise the empty string. Used
	// by the daemon to populate its image_kinds index at ingestion
	// time so subsequent listings don't have to re-derive the kind
	// from each backend's idiosyncratic surface (docker config Labels
	// for bins, manifest annotations for agents). Cheap on both
	// backends: system reads the manifest blob it already has;
	// docker reads the same Config.Labels[LabelArtifactType] today's
	// Inspect path used to read.
	ManifestKind(ctx context.Context, ref string) (string, error)
}

type ResolvedConfig struct {
	ID        uuid.UUID         `yaml:"id" json:"id"`
	Name      string            `yaml:"name" json:"name"`
	Model     string            `yaml:"model" json:"model"`
	Workspace string            `yaml:"workspace,omitempty" json:"workspace,omitempty"`
	Image     *OCIRef           `yaml:"image,omitempty" json:"image,omitempty"`
	Runtime   *RuntimeRef       `yaml:"runtime,omitempty" json:"runtime,omitempty"`
	Configs   map[string]string `yaml:"configs,omitempty" json:"configs,omitempty"`
	// Capabilities enumerates the LLM-facing tool functions the
	// runtime image registers (NOT per-BIN tools — those live in
	// Tools). Each carries its description so the model can read
	// what every tool does straight out of agent.yaml. Populated
	// by the daemon at materialise time. A future Agentfile
	// CAPABILITY directive will gate individual entries.
	Capabilities []Capability   `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	Envs         []*spec.Env    `yaml:"envs,omitempty" json:"envs,omitempty"`
	Mounts       []*spec.Mount  `yaml:"mounts,omitempty" json:"mounts,omitempty"`
	Context      []ContextEntry `yaml:"context,omitempty" json:"context,omitempty"`
	Tools        []ResolvedTool `yaml:"tools,omitempty" json:"tools,omitempty"`
	// Exec is the operator-supplied entrypoint override (e.g. a
	// custom runtime invocation). Lives in daemon.db; never on
	// disk in agent.yaml.
	Exec    []string `yaml:"-" json:"-"`
	Addr    string   `yaml:"-" json:"-"`
	APIBase string   `yaml:"-" json:"-"`
	APIKey  string   `yaml:"-" json:"-"`
}

type ResolvedTool struct {
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Binary      string `yaml:"binary" json:"binary"`
	Ref         string `yaml:"ref,omitempty" json:"ref,omitempty"`
	Digest      string `yaml:"digest,omitempty" json:"digest,omitempty"`
	Usage       string `yaml:"usage,omitempty" json:"usage,omitempty"`
}

type Runtime struct {
	Source         *spec.Agentfile `yaml:"-" json:"-"`
	ResolvedConfig `yaml:",inline" json:",inline"`
}

type RuntimeRef struct {
	Ref    string `yaml:"ref" json:"ref"`
	Digest string `yaml:"digest,omitempty" json:"digest,omitempty"`
	Binary string `yaml:"binary,omitempty" json:"binary,omitempty"`
}

type SessionDeleter interface {
	DeleteSession(ctx context.Context, sessionID string) error
}

type SessionInfo struct {
	ID           string
	MessageCount int
	LastActive   time.Time
}

type SessionLister interface {
	ListSessions(ctx context.Context) ([]SessionInfo, error)
}

type SessionMessage struct {
	Role         string
	Content      string
	BranchesJSON string
	ActiveBranch int
	CreatedAt    time.Time
}

type SessionReader interface {
	ListSessionMessages(ctx context.Context, sessionID string, limit int) ([]SessionMessage, error)
}

type Status uint8

type StatusObserver interface {
	// Status returns the current state.
	Status() Status
	// FailureReason returns the cause when Status() == StatusFailed.
	// Returns FailureNone for non-failed states; callers can render
	// the zero value as the empty string via FailureReason.String().
	FailureReason() FailureReason
	// SubscribeStatus returns a channel of status transitions and a cancel
	// function that closes the channel. Sends are non-blocking: slow
	// subscribers may miss intermediate transitions; call Status() to
	// resync. Always call cancel to avoid leaking the subscription.
	SubscribeStatus() (<-chan Status, func())
}

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

type StreamPrompter interface {
	PromptStream(ctx context.Context, req PromptRequest, cb func(PromptEvent)) error
}

type WorkspaceView struct {
	// Root is what the agent considers the root of its tree —
	// the directory under which `etc/`, `home/`, `tmp/`, `var/`
	// live (and `workspace/` when WorkspaceDir is empty).
	// OTTERS_AGENT_ROOT in the spawned env points here.
	Root string

	// WorkspaceDir is the agent-visible path to the scratch dir.
	// When empty, falls back to `<Root>/workspace`. Docker
	// overrides this to `/workspace` so the user-facing CWD is
	// not `/agent/workspace` but a clean top-level path; the
	// host directory is bind-mounted there in addition to the
	// FHS root.
	WorkspaceDir string

	// BinDirs are the absolute paths the runtime resolves BIN
	// tools against, in the agent's view. System: a single
	// `<Root>/usr/bin`. Docker: one entry per BIN, e.g.
	// `/opt/bins/ping`, `/opt/bins/jq`.
	BinDirs []string

	// RuntimeBin is the absolute path of the runtime binary in
	// the agent's view. System: `<Root>/usr/local/bin/runtime`.
	// Docker: `/opt/runtime/runtime`.
	RuntimeBin string

	// Isolated reports whether a real sandbox boundary separates
	// the host from the agent. Docker: true. System: false.
	// Affects WORKSPACE.md phrasing — isolated agents are told
	// "you're in a container; everything below is the in-container
	// path"; non-isolated ones are told "no chroot, real host
	// paths in tool calls".
	Isolated bool
}