explore

type Action struct {
	Kind ActionKind
	// Target locates the element the action addresses, nil for
	// screen-level actions (back, swipe by direction, launch).
	Target *Locator
	// Text is input text, key name, link, or assertion text by kind.
	Text string
	// Direction is up/down/left/right for swipe and scroll kinds.
	Direction string
	// Masked marks an input whose real text was withheld because it may
	// have landed in a secure field; Text then carries MaskedText. The
	// flag, not the text, is the signal — a user can type a literal "***".
	Masked bool
}

type ActionKind string

type Analyst interface {
	Report(ctx context.Context, report *SessionReport) (string, error)
}

type ChatRequest struct {
	Messages []Message
	Tools    []ToolSpec
	// ForceTool requires the model to call some tool this turn.
	ForceTool bool
	// MaxTokens caps the reply when positive.
	MaxTokens int
}

type ChatResponse struct {
	Message Message
	Usage   Usage
}

type Config struct {
	// AppID is the application under exploration (bundle id or package).
	AppID string
	// Platform is the selected execution platform token name
	// (android, ios, ios-physical, web).
	Platform string
	// StateDir is the per-app persistent directory holding knowledge,
	// learned recipes, plans, and research caches across sessions.
	StateDir string
	// OutputDir receives per-session artifacts: reports, exported flows,
	// screenshots, recordings.
	OutputDir string
	// MaxTests bounds how many scenarios the session may execute.
	// Zero means the caller must supply a positive budget; the runner
	// refuses a zero budget rather than defaulting to unlimited.
	MaxTests int
	// MaxStepsPerTest bounds the tester tool loop for one scenario.
	MaxStepsPerTest int
	// Styles are planning style names rotated across iterations.
	Styles []string
	// PilotEnabled turns on the supervisor conversation. When disabled,
	// scenario verdicts fall back to expected-outcome matching alone.
	PilotEnabled bool
	// RecordVideo starts a screen recording for the session when the
	// platform supports it.
	RecordVideo bool
	// SessionName tags entities the tester creates so reports and
	// cleanup can identify them.
	SessionName string
	// Clock supplies time; nil means real time.
	Clock func() time.Time
}

type Crew struct {
	Observer   Observer
	Researcher Researcher
	Planner    Planner
	Tester     Tester
	Navigator  Navigator
	Analyst    Analyst
	Exporter   Exporter
}

type ExperienceStore interface {
	// Index lists entry titles for a screen, cheap enough to inject
	// into every conversation.
	Index(ctx context.Context, screen ScreenSignature) ([]string, error)
	// Get fetches one entry body by title.
	Get(ctx context.Context, screen ScreenSignature, title string) (string, error)
	// Record appends or replaces an entry for a screen. Secrets must
	// be redacted before writing.
	Record(ctx context.Context, screen ScreenSignature, entry MemoryEntry) error
}

type Exporter interface {
	ExportFlow(result *TestResult, appID string) ([]byte, error)
}

type FlatElement struct {
	EIDX int
	Node device.TreeNode
	// Path is the child-index chain from the root, e.g. "0/2/1".
	Path string
	// Depth is the nesting level, root = 0.
	Depth int
}

type KnowledgeStore interface {
	// Match returns the hint bodies that apply to a screen.
	Match(ctx context.Context, screen ScreenSignature) ([]string, error)
}

type LLM interface {
	Chat(ctx context.Context, request ChatRequest) (ChatResponse, error)
}

type Locator struct {
	Kind  LocatorKind
	Value string
	// Index disambiguates when Value matches several elements.
	Index int
	// Label names the element for a human reader when Value cannot: a point
	// or a tree path says where, never what. Nothing matches on it and the
	// exporter never writes it -- an element reached by coordinate is reached
	// by coordinate on replay too.
	Label string
}

type LocatorKind string

type LoopResult struct {
	// Messages is the full conversation including tool turns.
	Messages []Message
	Usage    Usage
	// Stopped reports that a handler requested the stop.
	Stopped bool
	// Exhausted reports that the iteration bound was hit before the
	// model finished.
	Exhausted bool
}

type MappedElement struct {
	EIDX     int
	Role     string
	Label    string
	Locators []Locator
	// Notes carries validation rules, data hints, or vision findings.
	Notes string
}

type MemoryEntry struct {
	Title string
	Body  string
}

type Message struct {
	Role       Role
	Text       string
	ImagePNG   []byte
	ToolCalls  []ToolCall
	ToolCallID string
}

type MissReason string

type ModelSet struct {
	Worker  LLM
	Manager LLM
	Vision  LLM
}

type Navigator interface {
	// EnsureReady prepares the app for exploration from any state.
	EnsureReady(ctx context.Context) (*ScreenState, error)
	// Reach tries to bring the app to the screen named by key,
	// using learned recipes first. The steps it took come back with the
	// screen: they are the prefix an exported flow needs to replay from
	// the same place, and only the caller of Reach knows the run they
	// belong to.
	Reach(ctx context.Context, key string) (*ScreenState, []StepRecord, error)
}

type Observer interface {
	Observe(ctx context.Context) (*ScreenState, error)
}

type OutcomeCheck struct {
	Expected string
	Met      bool
	Evidence string
	// Missed classifies an unmet outcome so the report can separate a
	// product defect from a planning artifact and from a missing verdict.
	Missed MissReason
	// Driver marks a check_visible probe the run made along the way. It is
	// evidence for the judge, never the scenario's verdict, so the report
	// never files one as a finding.
	Driver bool
}

type Plan struct {
	AppID     string
	CreatedAt time.Time
	Scenarios []Scenario
}

type PlanRequest struct {
	Map *UIMap
	// Style selects the planning style for this iteration.
	Style string
	// Existing lists scenario names already planned or executed, for
	// dedup.
	Existing []string
	// Unmet lists expected outcomes earlier runs of this session looked for
	// and did not find. Naming them keeps the planner from writing the same
	// expectation every round: mmx78 planned the same invented day view
	// three times.
	//
	// The claim is deliberately weak. The earlier field carried only the
	// outcomes a judge ruled the app never offers, which is a judgement no
	// session ever made -- every report says "0 with an expectation the app
	// never promised" while filing defects of exactly that kind. "A run
	// looked and did not find it" needs nobody's opinion.
	Unmet []string
	// Focus optionally narrows planning to one feature or region.
	Focus string
	// Budget caps how many scenarios to emit.
	Budget int
}

type Planner interface {
	PlanNext(ctx context.Context, request PlanRequest) ([]Scenario, error)
}

type Priority string

type Researcher interface {
	Research(ctx context.Context, state *ScreenState) (*UIMap, error)
}

type Role string

type Scenario struct {
	Name     string
	Priority Priority
	// Style names the planning style that produced this scenario.
	Style string
	// StartScreen is the screen key the scenario begins on.
	StartScreen string
	Steps       []string
	Expected    []string
	Status      ScenarioStatus
}

type ScenarioStatus string

type ScreenSignature struct {
	// AppID scopes the signature to the application.
	AppID string
	// Salient holds a few stable prominent labels (screen title, tab
	// name) that make the signature human-readable.
	Salient []string
	// TreeDigest is a short hex digest of the normalized flattened
	// accessibility tree.
	TreeDigest string
}

type ScreenState struct {
	Signature     ScreenSignature
	Hierarchy     device.TreeNode
	Elements      []FlatElement
	ScreenshotPNG []byte
	CapturedAt    time.Time
	// DialogActive reports that a modal surface (alert, sheet, dialog)
	// dominates the screen.
	DialogActive bool
	// Viewport is the screen the device reported when this state was
	// captured. A zero one means nobody measured, not a screen of no size.
	Viewport device.Bounds
}

type Section struct {
	Name     string
	Notes    string
	Elements []MappedElement
	// Trigger records the action that revealed a hidden section
	// (expanded row, opened sheet), empty for always-visible sections.
	Trigger string
}

type SessionReport struct {
	AppID    string
	Platform string
	Results  []TestResult
	// Markdown is the rendered analyst report.
	Markdown string
	Usage    Usage
	Started  time.Time
	Finished time.Time
}

type StepRecord struct {
	Index   int
	Action  Action
	Status  StepStatus
	Note    string
	Before  ScreenSignature
	After   ScreenSignature
	At      time.Time
	ErrText string
	// TargetMiss marks a step that failed because the screen has no element
	// the agent's target names. The device answered; the agent aimed at
	// nothing, so a report must not read this as broken equipment.
	TargetMiss bool
}

type StepStatus string

type TargetMissError struct {
	Reason string
}

type TestResult struct {
	Scenario Scenario
	Status   TestStatus
	// Prelude is what the navigator did to bring the app to the scenario's
	// start screen, before the run's own first step. A relaunch does not
	// land on that screen -- an app restores its last view -- so a flow
	// exported without this walk begins somewhere the recording never was.
	Prelude  []StepRecord
	Steps    []StepRecord
	Outcomes []OutcomeCheck
	Notes    []string
	Started  time.Time
	Finished time.Time
	// Verdict is the supervisor summary when the pilot ran, or the
	// outcome-matching summary otherwise.
	Verdict string
}

type TestStatus string

type Tester interface {
	RunScenario(ctx context.Context, scenario Scenario, start *ScreenState) (*TestResult, error)
}

type ToolBox struct {
	Specs    []ToolSpec
	Handlers map[string]ToolHandler
}

type ToolCall struct {
	ID        string
	Name      string
	Arguments json.RawMessage
}

type ToolHandler func(ctx context.Context, args json.RawMessage) (string, error)

type ToolSpec struct {
	Name        string
	Description string
	Schema      json.RawMessage
}

type UIMap struct {
	Screen    ScreenSignature
	Sections  []Section
	CreatedAt time.Time
	// Markdown is the rendered map given to planning and testing
	// conversations.
	Markdown string
}

type Usage struct {
	InputTokens  int
	OutputTokens int
}