actor

type ActionOutcome struct {
	Kind ActionOutcomeKind `json:"kind"`
	// Detail is a human-readable explanation, set for
	// ActionSkippedInvalid/ActionResolutionFailed (why), empty otherwise.
	Detail string `json:"detail"`
}

type ActionOutcomeKind string

type Actuator interface {
	SubmitText(chatID int64, user platform.User, text string) error
	SubmitClick(chatID int64, user platform.User, data string, targetMessageID int) error
	WaitForMessage(chatID int64, consumed int, timeout time.Duration) (*platform.Message, bool)
	WaitForEdit(chatID int64, messageID int, afterVersion int, timeout time.Duration) (*platform.Message, bool)
}

type Cassette struct {
	// ProviderConfig is a free-form, caller-supplied description of the
	// wrapped provider's configuration (model, system prompt, temperature,
	// ...), folded into every entry's key so replaying against a
	// differently configured provider is a cache miss, not a silent
	// mismatch.
	ProviderConfig string `json:"providerConfig"`

	Entries []CassetteEntry `json:"entries"`
}

type CassetteEntry struct {
	// Key is the deterministic hash of ProviderConfig plus the canonical
	// prompt this entry was recorded for; see promptKey.
	Key string `json:"key"`
	// PromptSummary is a short, human-readable description of the prompt —
	// for PR review and for ErrCassetteCacheMiss's error message. It is not
	// itself used to look the entry up (Key is).
	PromptSummary string   `json:"promptSummary"`
	Proposal      Proposal `json:"proposal"`
	Usage         Usage    `json:"usage"`
}

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

type Config struct {
	// ChatID and User identify the conversation the loop drives, exactly as
	// passed to Actuator.SubmitText/SubmitClick.
	ChatID int64
	User   platform.User

	// HistoryWindow bounds how many recent LoopEvents are fed to each
	// Prompt.History. Defaults to 10 if <= 0.
	HistoryWindow int
	// NonProgressLimit is how many consecutive invalid-or-no-effect
	// proposals the loop tolerates for one task before stopping the
	// campaign itself (via goal.CampaignState.Abort) rather than looping
	// forever. Defaults to 3 if <= 0.
	NonProgressLimit int
	// ActWaitTimeout bounds how long the loop waits, after acting, for the
	// platform's raw reply (WaitForMessage/WaitForEdit) that the journal
	// read (observe.Engine.Observe) already showed exists. Defaults to 5s
	// if <= 0.
	ActWaitTimeout time.Duration

	// Now supplies the loop's notion of the current time, stamped onto
	// every LoopEvent.At. Must not be nil; pass the same clock given to the
	// Loop's goal.CampaignState so timestamps and budget decisions agree.
	Now func() time.Time

	// DisableObservationRetention turns off the Loop's retention of every
	// observe.Observation it produces (see Loop.Observations). Retention is
	// ON by default (the zero value is false) — a campaign's entire purpose
	// is producing evidence, and the retained observation bodies are what
	// let a run bundle (chatwright.dev/sdk's Bundle) stay self-contained: a
	// player can show exactly
	// what the actor saw at each step without re-deriving it from a
	// transcript. Set this true only when a campaign is long enough, or
	// memory-bounded enough, that holding every Observation body for its
	// whole run is not affordable; Loop.Events (and campaign.Report) are
	// unaffected either way, since neither depends on retention.
	DisableObservationRetention bool
}

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

type LoopEvent struct {
	// Index is 0-based and monotonic across one Loop's lifetime (not just
	// one task), so it is stable to reference from a campaign.Finding.
	Index int `json:"index"`
	// At is stamped from the loop's injected clock (Config.Now), never
	// time.Now, so a run's timeline is reproducible.
	At time.Time `json:"at"`
	// TaskID is the task this iteration was attempting.
	TaskID string `json:"taskId"`

	// ObservationSequence is the observe.Observation.Sequence this
	// iteration observed before proposing — the same value a
	// campaign.Finding's evidence links back to.
	ObservationSequence int64 `json:"observationSequence"`

	Proposal Proposal `json:"proposal"`
	Usage    Usage    `json:"usage"`

	// Validation is the loop's validate-step outcome for Proposal. It is
	// only Checked for ProposeClick — the loop has nothing to validate
	// against observe for a send-text, task-done or give-up proposal.
	Validation ValidationOutcome `json:"validation"`

	// Action is what actually happened when the loop tried to act on
	// Proposal (or why it did not).
	Action ActionOutcome `json:"action"`
}

type Mode string

type Prompt struct {
	GoalID          string
	GoalTitle       string
	GoalDescription string
	Constraints     []string

	TaskID              string
	TaskTitle           string
	TaskSuccessCriteria string

	// Observation is the current semantic snapshot: visible messages,
	// available actions and explicit changes. A Provider proposing
	// ProposeClick must copy ActionID from an action listed here, and
	// ObservationSequence from Observation.Sequence.
	Observation observe.Observation

	// History is the loop's last N LoopEvents preceding this prompt, oldest
	// first; N is the loop's configured history window (Config.HistoryWindow).
	// It includes invalid/no-effect attempts, so a Provider can see (and
	// avoid repeating) what did not work.
	History []LoopEvent
}

type Proposal struct {
	Kind ProposalKind `json:"kind"`

	// Text is set for ProposeSendText: the text to send as the user.
	Text string `json:"text"`

	// ActionID is set for ProposeClick: an observe.AvailableAction.ID drawn
	// from the Prompt's Observation.
	ActionID string `json:"actionId"`
	// ObservationSequence is the Observation.Sequence the proposal was
	// chosen from. Required for ProposeClick (fed to observe.Engine.Validate
	// as observe.ActionProposal.ObservationSequence); ignored otherwise.
	ObservationSequence int64 `json:"observationSequence"`

	// Rationale is free text explaining the choice — never private
	// chain-of-thought, just enough for a developer or the campaign report
	// to understand why the actor did this.
	Rationale string `json:"rationale"`
}

type ProposalKind string

type Provider interface {
	Propose(ctx context.Context, prompt Prompt) (Proposal, Usage, error)
}

type ProviderFunc func(ctx context.Context, prompt Prompt) (Proposal, Usage, error)

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

type TaskResult struct {
	TaskID string
	// Status is the task's goal.TaskStatus when RunTask returned.
	Status goal.TaskStatus
	// Stopped is true if the whole campaign had stopped (any
	// goal.StopReason, including this task completing the goal) by the time
	// RunTask returned.
	Stopped bool
	// NonProgress is true if this task's run ended specifically via the
	// loop's own non-progress detection (Config.NonProgressLimit) rather
	// than a goal.CampaignState-native stop. When true, Stopped is also
	// true: the loop stops the whole campaign (via Abort) rather than
	// silently moving on to another task, since non-progress on one task is
	// evidence the actor itself is stuck, not that the task is unreachable.
	NonProgress bool
}

type Usage struct {
	Model        string        `json:"model"`
	InputTokens  int           `json:"inputTokens"`
	OutputTokens int           `json:"outputTokens"`
	Latency      time.Duration `json:"latencyNanoseconds"`
	Cost         *float64      `json:"cost,omitempty"`
}

type ValidationOutcome struct {
	// Checked is false for proposal kinds observe.Validate does not apply
	// to (ProposeSendText, ProposeTaskDone, ProposeGiveUp); Verdict and
	// Reason are meaningless when Checked is false.
	Checked bool            `json:"checked"`
	Verdict observe.Verdict `json:"verdict"`
	Reason  string          `json:"reason"`
}