loop

type CompactStats struct {
	BeforeMsgs   int
	AfterMsgs    int
	BeforeTokens int
	AfterTokens  int
	Duration     time.Duration
}

type EmptyCompletionError struct {
	Streak int
}

type Engine struct {
	Provider llm.Provider
	Tools    *tools.Registry
	Skills   *skills.Registry
	Memory   KnowledgeStore
	Sessions *session.Rollout
	// Waggle, when non-nil, observes read-only tool calls so repeated routes can
	// be crystallized into reusable exec-skills (procedure memory). nil disables.
	Waggle *waggle.Manager
	// Replay, when non-nil, follows previously crystallized routes: after a tool
	// batch it matches the recent read-only calls against stored waggle prefixes
	// and, on a confident match, runs the route's remaining read-only steps off
	// the model's path, folding their output into the triggering tool result so
	// the model skips the round-trips. Zero prompt cost (matching is in Go). nil
	// disables.
	Replay *waggle.Replayer
	Cfg    config.Config
	Cwd    string
	Stdout io.Writer
	// SteerCh, when non-nil, is drained at the top of each iteration to
	// inject mid-turn user steering between LLM rounds.
	SteerCh chan string
	// StreamCh, when non-nil, receives every text delta produced by the
	// provider in lieu of writing them to Stdout. The TUI uses this to
	// route deltas through bubbletea so the alt-screen isn't corrupted.
	// Sends are non-blocking — a slow consumer drops deltas rather than
	// stalling the model stream.
	StreamCh chan string
	// ThinkCh, when non-nil, receives every chain-of-thought delta as it
	// arrives. Separate from StreamCh so the TUI can render reasoning
	// live in a dimmed/italic block above the answer instead of waiting
	// for the whole thinking buffer to flush at end-of-stream. Sends are
	// non-blocking — slow consumer drops deltas.
	ThinkCh chan string
	// LiveMsgCh, when non-nil, receives every assistant + tool message as
	// it's persisted, so a UI can render tool_use / tool_result cards in
	// real time instead of only after Run returns. User messages are NOT
	// sent (the caller's UI already shows an optimistic copy). Sends are
	// non-blocking — a stalled consumer doesn't stall the loop.
	LiveMsgCh chan types.Message
	// WarnCh, when non-nil, receives transient operational notices: stream
	// retries, watchdog stalls, etc. The TUI fades them as a small chrome
	// line so the user knows something happened without the turn aborting.
	// Sends are non-blocking — a slow consumer drops notices.
	WarnCh chan string
	// JSONEmitter, when non-nil, receives one NDJSON event per significant
	// happening (text delta, tool use, tool result, done, error) and
	// suppresses the human-readable text-delta write to Stdout.
	JSONEmitter *jsonmode.Emitter
	// Costs, when non-nil, accumulates per-turn usage/dollar events. The
	// TUI reads from the same tracker to drive the top-bar total and the
	// /cost monitor pane.
	Costs *cost.Tracker
	// InitialMessages, when non-nil, seeds the in-memory message list at
	// the start of each Run so the model receives prior turns as context.
	// The TUI refreshes this per submit; `bee back <id>` sets it from disk.
	// Messages here are NOT re-appended to the rollout — they're already on
	// disk or never were (caller's responsibility).
	InitialMessages []types.Message
	// Rebuild, when non-nil, is invoked by the TUI after a mid-session
	// provider/model switch (`/model` or the picker). The closure owns
	// re-creating Provider + Memory from the current Cfg so the next turn
	// talks to the new backend instead of the original one cached at Engine
	// construction. nil = no live switching (headless, hive workers).
	Rebuild func(*Engine) error

	// OnceAllowTools force-allows plan-only tools (e.g. ask_user) for the next
	// Run, regardless of the active role. A prompt skill sets it from its
	// frontmatter `tools` list so /plan can ask the user even from worker.
	// Only plan-only tools are honoured — it can't re-enable write/bash that a
	// read-only turn legitimately strips. Cleared at the top of each Run.
	OnceAllowTools []string

	// SkipPostureClassifier disables the worker read-only/act classifier for
	// this engine, so a worker turn always gets the full tool surface. Set for
	// the scripted-provider test harness (the extra side Stream call would
	// desync scripted response counts) and for callers that want byte-for-byte
	// "always act" worker behavior.
	SkipPostureClassifier bool
	// contains filtered or unexported fields
}

type EscalateError struct {
	Reason     string
	NextAction string
	Options    []string
}

type FormatStrikeError struct {
	Streak int
}

type KnowledgeStore interface {
	Query(ctx context.Context, query string, recentTools []string) ([]knowledge.Record, error)
}

type MaxIterationsError struct {
	Limit int
}

type Observation struct {
	Sig                         ToolCallSignature
	RepeatCount                 int  // how many times this exact Sig has fired this Run
	ConsecutiveSameToolFailures int  // streak of failures on the same tool name (any args)
	ConsecutiveSameSigFailures  int  // streak of failures on the same (tool,args) sig
	IsTwoStrike                 bool // same Sig failed twice in a row → nudge (no longer bails)
}

type PerToolFailureError struct {
	Use    types.ToolUse
	Tool   string
	Streak int
	Class  string
}

type RecapResult struct {
	Text    string
	Skipped bool
	Err     error
}

type RepeatStreamError struct {
	Streak int
}

type ResumeDecision struct {
	Resume       bool
	Continuation string // synthetic user message to re-trigger with
	Reason       string // short label for the warn line / stderr
}

type Role string

type RunResult struct {
	Messages  []types.Message
	FinalText string
}

type ToolCallSignature struct {
	Name     string
	ArgsHash string
}

type TruncatedStreamError struct {
	Streak int
}

type TwoStrikeError struct {
	Use   types.ToolUse
	Class string // tool-error class tag (toolErrNotFound, toolErrTimeout, etc.)
}