ux

type AgentError struct {
	SchemaVersion string         `json:"schema_version"`
	ErrorCode     string         `json:"error_code"`
	Error         string         `json:"error"`
	Actionable    string         `json:"actionable_step,omitempty"`
	Details       map[string]any `json:"details,omitempty"`
}

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

type Audience interface {
	// Ask prompts for missing information. Humans get a TUI prompt; agents get a
	// typed CodedError explaining the missing flag (no interactive fallback).
	Ask(question, flagName string, required bool) (string, error)

	// AskConfirm prompts for a destructive action. Humans get [y/N]; agents
	// auto-reject unless the global --yes was passed.
	AskConfirm(warning string) (bool, error)

	// Render writes a success payload to stdout. Intentionally VOID: the only
	// realistic failure is a marshal error on an exotic value (channel/func) — a
	// programmer bug — which marshalRedacted turns into a guaranteed-encodable error
	// envelope, so stdout always carries exactly one valid JSON document. Callers
	// treat Render as a terminal "this succeeded".
	Render(data any)

	// ReportError writes a failure to stderr (never stdout — stdout is reserved for
	// Render). Humans get a red line; agents get the structured error envelope. Both
	// pass the byte-level redaction backstop (review M6).
	ReportError(err error, actionableNextStep string)

	// Theme returns the active palette.
	Theme() Palette

	// IsFenced reports whether this mode is forbidden from state-mutating admin
	// commands (the root interceptor enforces it — impl/3.2 §2).
	IsFenced() bool

	// ForcesNoColor reports whether ANSI must be suppressed regardless of theme, to
	// protect downstream machine parsers.
	ForcesNoColor() bool
}

type CodedError struct {
	Code       string         // e.g. "MISSING_ARGUMENT", "BROKER_DENIED"
	Msg        string         // human/LLM-readable prose (redacted on output)
	Actionable string         // machine-runnable recovery step, when one exists
	Details    map[string]any // e.g. {"agent_directive": ..., "http_status": 403}
	// contains filtered or unexported fields
}

type Export struct {
	SchemaVersion string `json:"schema_version"`
	// TraceID is the correlation pivot the export was queried by (impl/5.0 §2).
	TraceID string `json:"trace_id,omitempty"`
	// Items is the exported records (kept as `any` so the same envelope serves any
	// export; history passes []control.ExecutionResponse).
	Items any `json:"items"`
	// Count is the number of exported records after filtering.
	Count int `json:"count"`
}

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

type List struct {
	SchemaVersion string `json:"schema_version"`
	Data          any    `json:"data"`
	// HasMore/NextCursor mirror the Jentic list APIs' cursor pagination. NextCursor
	// is omitted when empty; HasMore is always present so an agent can branch on it
	// without a null check.
	HasMore    bool   `json:"has_more"`
	NextCursor string `json:"next_cursor,omitempty"`
	// Meta carries command-specific summary fields that are NOT the collection
	// itself (e.g. catalog's catalog_total / manifest_age_seconds). Kept under one
	// key so the top level stays a stable, closed shape across every list command;
	// omitted entirely when a command has no summary.
	Meta map[string]any `json:"meta,omitempty"`
}

type Page struct {
	SchemaVersion string `json:"schema_version"`
	Items         any    `json:"items"`
	// NextToken is the opaque cursor for the next page; empty on the last page.
	NextToken string `json:"next_token,omitempty"`
}

type Palette = theme.Palette

type Plan struct {
	SchemaVersion string `json:"schema_version"`
	Operation     string `json:"operation"`
	DryRun        bool   `json:"dry_run"`
	Payload       any    `json:"payload,omitempty"`
}

type Result struct {
	// SchemaVersion pins the envelope shape for agents (13 §2/§6). Call sites may
	// leave it empty; marshalRedacted stamps the current version at render time.
	SchemaVersion string `json:"schema_version"`
	// Status is the outcome verb (StatusCreated, StatusSwitched, ...).
	Status string `json:"status"`
	// Resource is the kind of thing acted on ("environment", "context", "identity").
	Resource string `json:"resource,omitempty"`
	// Name is the human/identifier name of the affected resource, when it has one.
	Name string `json:"name,omitempty"`
	// ID is the server- or client-assigned identifier, when one was produced.
	ID string `json:"id,omitempty"`
	// Message is optional human-oriented context (e.g. "awaiting operator approval").
	Message string `json:"message,omitempty"`
	// Fields is the escape hatch for genuinely command-specific data. Prefer a
	// first-class field above; use this only when nothing else fits.
	Fields map[string]any `json:"fields,omitempty"`
}