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 BudgetBurn struct {
	Steps            float64 `json:"steps"`
	Duration         float64 `json:"duration"`
	Cost             float64 `json:"cost"`
	RepeatedFailures float64 `json:"repeatedFailures"`
}

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

	// DisableOvershootProbe turns off the Loop's overshoot probe (see
	// RunTask's evidence-defined-completion handling): the one extra
	// Provider.Propose call RunTask otherwise issues, records and never
	// executes the moment a task's goal.Task.Criteria are found to hold,
	// solely to measure whether the actor would have kept acting —
	// spec/ideas/evidence-defined-completion.md's "stops-when-done rate".
	// The probe is ON by default (the zero value is false), since the
	// idea's own MVP proof requires it; set this true to skip the extra
	// call's cost when that measurement is not wanted.
	DisableOvershootProbe bool

	// OnProgress, when non-nil, is called with a ProgressSnapshot once per
	// loop iteration and once at each task-start/task-end boundary — pure,
	// derived, in-process reporting (spec/ideas/campaign-progress-reporting.md):
	// nothing it receives is added to Loop.Events, a campaign.Report or any
	// run bundle. Called synchronously, on the same goroutine RunTask runs
	// on; a slow or blocking OnProgress delays the loop itself. Nil (the
	// zero value) means no progress reporting.
	OnProgress func(ProgressSnapshot)
}

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"`

	// ProposeError is set exactly when this iteration's call to
	// Provider.Propose returned an error: it carries that error's own
	// message (error.Error()), and Proposal, Usage, Validation and Action
	// are all their zero value — there was nothing to validate or act on.
	// Empty for every iteration that got as far as a Proposal.
	//
	// This field exists so a failed Propose call still leaves a LoopEvent
	// behind — see RunTask, which appends one before returning the error —
	// instead of vanishing from the record with only a returned Go error
	// nobody downstream of the loop (a campaign.Report, a run bundle) ever
	// sees (github.com/chatwright/runtime-go issue #4).
	ProposeError string `json:"proposeError,omitempty"`
}

type Mode string

type ProgressPhase string

type ProgressSnapshot struct {
	Phase ProgressPhase `json:"phase"`

	GoalID string `json:"goalId"`
	TaskID string `json:"taskId"`
	// TaskIndex is TaskID's 1-based position within the Goal's declared
	// Tasks — the idea's "task j/m" gauge (j).
	TaskIndex int `json:"taskIndex"`
	// TaskCount is the Goal's total declared task count — the idea's
	// "task j/m" gauge (m).
	TaskCount int `json:"taskCount"`
	// TasksCompleted is how many of the Goal's tasks are goal.TaskCompleted
	// as of this snapshot (campaign-wide, not just this task).
	TasksCompleted int `json:"tasksCompleted"`

	// Iteration is this task's own 1-based loop-iteration count: 0 at
	// ProgressTaskStarted, incrementing by one per ProgressIteration.
	Iteration int `json:"iteration"`

	Budgets goal.Budgets `json:"budgets"`
	Burn    BudgetBurn   `json:"burn"`

	// NonProgressStreak mirrors Loop.RunTask's own consecutive
	// invalid-or-no-effect counter for this task.
	NonProgressStreak int `json:"nonProgressStreak"`
	// RetryCounts tallies this task's own recorded LoopEvents so far, by
	// ActionOutcomeKind — the idea's "retry counts by cause" gauge.
	RetryCounts map[ActionOutcomeKind]int `json:"retryCounts"`

	// Stopped and StopReason mirror goal.CampaignState.Stopped/StopReason
	// as of this snapshot.
	Stopped    bool            `json:"stopped"`
	StopReason goal.StopReason `json:"stopReason"`
}

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); Freshness and
	// Reason are meaningless when Checked is false.
	Checked   bool              `json:"checked"`
	Freshness observe.Freshness `json:"freshness"`
	Reason    string            `json:"reason"`
}