turn

type AssembledToolCall struct {
	ID        string
	Name      string
	Arguments string
}

type Deps struct {
	Active           *model.ActiveState
	Store            *sessions.Store
	Client           provider.Client
	Sink             Sink
	Flush            FlushHook
	FlushUnsupported FlushHook
	OnToolCalls      ToolCallHook

	TurnID string

	// A nil SupportedEffort lookup exposes only no-reasoning.
	SupportedEffort func(providerID, modelID string) []string

	// SuggestFollowup routes an intercepted suggest_followup tool call to the
	// TUI: label is the short imperative shown as Tab-to-accept ghost text and prompt is
	// the text prefilled when the user accepts. The agentic loop fires it instead of
	// dispatching or persisting that call, so the suggestion is purely ephemeral UI state
	// and never reaches the session record or transcript. Optional and nil-safe: a
	// standalone Runner or a test that does not wire it simply drops the suggestion (the
	// call is still omitted from the records).
	SuggestFollowup func(label, prompt string)

	// OnToolActivity surfaces a tool-call round's about-to-run calls as live, inline
	// transcript lines, one formatted line per call in assembled order (see
	// ToolActivityLines). The agentic loop fires it once per tool-call round, after the
	// calls are assembled and before they are scheduled/dispatched, so the user sees what
	// is about to run — and a denied call still shows its line. It is derived purely from
	// the already-assembled calls, so it costs no extra provider tokens. Optional and
	// nil-safe: a standalone Runner or a test that does not wire it simply emits nothing.
	OnToolActivity func(lines []string)
	// SealPartial commits a buffered pre-tool reply that OnToolActivity left unsealed. The loop
	// calls it after dispatch unless the time limit cancelled the round, which rolls it back.
	SealPartial func()

	OnEditPatch func(patch string)

	// Progress reports the cumulative retained assistant-content rune count as the
	// reply streams — an approximate in-flight progress signal, not exact tokens
	// (stream usage only arrives in the final chunk). It remains a retained-rune
	// callback for tests and any other consumer, but production no longer feeds it to
	// the token indicator: that indicator is wired to exact per-round Usage only,
	// because retained runes routinely exceed the round's exact output tokens and feeding
	// them in would make the ↓ figure climb then drop (see Usage / UsageAcc). May be nil.
	// It is called in arrival order on the single stream goroutine, like Sink. In an
	// agentic turn ToolLoop wraps this so the reported count is cumulative across provider
	// rounds (prior rounds' retained chars plus the current round's), keeping the live
	// signal from shrinking when a fresh per-round Runner resets its own count to zero.
	Progress func(retainedChars int)
	// Usage reports the exact provider token usage as cumulative input/output totals,
	// feeding the in-flight indicator's exact figure. It fires once per
	// successful round under a ToolLoop and once total for a bare Runner: under a
	// ToolLoop (UsageAcc != nil) the loop owns emission and fires it after every round
	// with the running turn total, so the ↑ input figure reaches each completed round's
	// real prompt cost immediately rather than only at turn end; a bare Runner
	// (UsageAcc == nil) fires it once on the natural non-tool completion that records
	// model_response. May be nil; it is not called when no usage chunk arrived in any
	// round (an interrupted or usage-missing turn). The count it reports is the summed
	// turn total (see UsageAcc), so it stays consistent with /status.
	Usage func(inputTokens, outputTokens int64)

	// UsageAcc accumulates the exact stream usage of every provider round in one
	// agentic turn so the final model_response and the Usage indicator report the
	// summed turn total rather than only the last round. ToolLoop owns one
	// per turn and threads the same pointer through every round's Deps; a standalone
	// Runner (no tool-call iteration) leaves it nil and records only its own round.
	UsageAcc *model.UsageAccumulator

	// SubmitStart is the wall-clock instant the user's input for this turn was
	// accepted at the pre-turn boundary (sessionturn.Persister), threaded through
	// bootstrap so the final provider round can record one end-to-end turn_latency
	// event (user submit → final answer) for the whole agentic turn. The same
	// value is carried onto every round's Deps, but only the final no-tool answer
	// records it, so a multi-round turn yields exactly one turn_latency. The zero
	// value means "not wired" (a standalone Runner or a test that does not exercise
	// turn latency), in which case no turn_latency is recorded.
	SubmitStart time.Time

	// SystemPrompt is the assembled system message — the active mode's base prompt,
	// the environment block, and the loaded AGENTS.md instructions. The bootstrap turn
	// wiring assembles it per dispatch and passes a stable snapshot here, so every
	// provider round in one turn uses the same prompt while a later /mode switch is
	// reflected on the next turn. When non-empty it leads each provider request as a
	// single synthetic system message before the conversation history; empty adds no
	// message.
	SystemPrompt string

	// Tools is the turn's mode-filtered advertised tool set, assembled once by
	// the bootstrap turn wiring per dispatch from the snapshotted active mode and the
	// realized registry plus the product-authored `bash` definition. It is threaded
	// onto every provider round's request through BuildRequest, so the tool-call
	// continuation rounds advertise the same set as the initial round and a /mode switch
	// only affects the next user turn. Empty (the default) advertises no tools, so the
	// request omits the `tools`/`tool_choice` fields.
	Tools []provider.ToolDefinition

	// SuggestFollowupDebug gates the development-only suggest_followup trace: when
	// true the turn loop appends ordered suggest_followup_debug events (advertised /
	// no-call / tool-call-seen / intercepted) to Store so a developer can see how far a
	// suggestion got. Off by default (false), so a normal turn records none of them. It
	// is append-only and best-effort — a missing diagnostic never affects the turn.
	SuggestFollowupDebug bool
	// Mode is the active interaction-mode key (plan/build/auto_edits) for this turn,
	// stamped onto the suggest_followup debug events alongside the provider/model from Active. It is
	// captured by bootstrap at dispatch (the turn package has no mode concept) and is only
	// read when SuggestFollowupDebug is on; empty otherwise.
	Mode string

	// Notice reports a provider/turn request failure as user-facing text (the rendered
	// failure line — for an HTTP error the friendly message, optionally with
	// the remediation hint line). It is called only
	// from the provider-failure paths of Run. The production binding commits it
	// as an in-place transcript line tied to the turn (App.CommitProviderError,
	// marshaled through the tview queue so it is safe from the background turn
	// goroutine) rather than a bottom-pinned notice, so a stale provider error can no
	// longer re-render below a later turn. Session-write failures take the
	// OnFailureWrite path instead and stay on the transient notice surface.
	Notice     func(text string)
	ToolNotice func(text string)
	// RenderNotice renders a provider-failure notice: line 1 is the caller-supplied
	// message (for an HTTP error, the friendly line from FriendlyHTTPMessage;
	// for transport/body failures, the synthetic surface), with the remediation hint
	// appended as line 2 when the (phase, reason, httpStatus) tuple matches the hint
	// table. The production binding is tui.RenderProviderRequestFailedNotice; injecting
	// it keeps this package free of internal/tui while still using the TUI's hint logic.
	RenderNotice func(verbatim, phase, reason string, httpStatus int) string
	// RenderRetryNotice renders the terminal provider-failure notice after auto-retry
	// gives up, enriching the normal notice with the number of attempts that were made
	// while preserving the provider-specific hint behavior. The production binding is
	// tui.RenderProviderRequestFailedAfterAttemptsNotice. Nil defaults to the normal
	// renderer with a generic "failed after N attempts" prefix on line 1.
	RenderRetryNotice func(verbatim, phase, reason string, httpStatus, attempts int) string
	// Interrupt seals the in-progress transcript reply as interrupted. It is
	// called on a real mid-stream transport drop, and on a user interrupt only
	// when the reply was still a held text-tool-call candidate that never reached the
	// Sink — so the ESC/CTRL-C path's own seal found no open stream to close. On an
	// ordinary user interrupt whose content already streamed, that path seals the reply
	// itself and this hook is not called.
	Interrupt func()
	// Finalize commits a naturally completed reply into the transcript so the
	// next turn starts a fresh buffer. It is called only on a successful non-tool
	// stream, after the assistant message and model_response are recorded.
	Finalize func()
	// FinalizeErr reports a failure to deliver what Finalize committed.
	FinalizeErr func() error
	// OnFailureWrite routes a real atomic-write failure from the
	// provider_request_failed flush through the per-turn write-failure
	// protocol (sessionfailures.HandleWriteFailure). It may be nil.
	OnFailureWrite events.WriteFailureHandler

	// Retry is the auto-retry policy for the turn's provider rounds. The
	// zero value (Enabled false) is the no-retry behavior: every provider
	// failure surfaces once, exactly as before. New applies the per-turn budget
	// default when an enabled policy leaves it unset. Production threads it from the
	// provider.retry settings block via bootstrap.
	Retry RetryPolicy
	// RetryBackoff reports that the next retry attempt has been scheduled and the
	// retry loop is entering backoff. nextAttempt is 1-based and names the provider
	// attempt that will run after the wait; totalAttempts is Retry.MaxAttempts. The
	// TUI uses it for the transient "Reconnecting..." indicator. Optional and nil-safe.
	RetryBackoff func(nextAttempt, totalAttempts int)
	// RetryResume reports that backoff completed and the provider round is about to be
	// re-issued, so the TUI can return the activity indicator to its normal working
	// state. Optional and nil-safe.
	RetryResume func()
	// RetryRecovered reports that a provider round completed successfully after one or
	// more scheduled retries. retries is the number of retries that were actually
	// issued, not the total attempt count. Optional and nil-safe.
	RetryRecovered func(retries int)
	// RollbackPartial removes the un-sealed in-progress reply line before a
	// discard-and-restart retry of a partial provider round, so the
	// regenerated answer does not stack on the discarded partial. The backend calls
	// it; the UI owns the visible transcript rollback against this seam. Optional and
	// nil-safe: New defaults it to a no-op, so a standalone Runner or a turn whose
	// stream never partially drops is unaffected.
	RollbackPartial func()

	IgnoredProviders      *IgnoredProviders
	ProviderIgnoredNotice func(text string)

	// OnProviderStreamIdle reports that the active provider round's stream has gone
	// quiet — no chunk for streamIdleThreshold. It fires at most once per provider round,
	// on the turn goroutine, after the durable provider_stream_idle event has been
	// flushed. Optional and nil-safe: New defaults it to a no-op.
	OnProviderStreamIdle func(StreamIdleInfo)
	// OnProviderStreamActivity reports that a chunk arrived after an idle crossing. It
	// fires at most once per round and only after OnProviderStreamIdle. Optional and
	// nil-safe: New defaults it to a no-op.
	OnProviderStreamActivity func()

	OnUserMessageAdded func(text string, parts []sessions.ContentPart)
	// contains filtered or unexported fields
}

type DispatchFailure struct {
	Err       error
	Reason    string
	Tool      string
	SessionID string
}

type FinalFlushError struct{ Err error }

type FlushHook func() error

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

type MoveTarget struct {
	Source      string
	Destination string
}

type PendingUserMessage struct {
	Text  string
	Parts []sessions.ContentPart
}

type PlannedToolCall struct {
	Call AssembledToolCall

	Deps    []string
	Targets []string

	// ContinueOnError withholds this unit's failure from the scheduler, so concurrent
	// siblings drain instead of being cancelled. The loop still reports the error before
	// persisting anything.
	ContinueOnError bool

	// PreRun runs before Run and skips it on error. It is separate from Run because a
	// wrapping dispatcher may replace Run, and a planner's guard must survive that.
	PreRun func(ctx context.Context) error

	Run func(ctx context.Context) (ToolResult, error)
}

type RetryPolicy struct {
	Enabled     bool
	MaxAttempts int
	BaseDelay   time.Duration
	MaxDelay    time.Duration
	Budget      time.Duration
}

type RoundReport struct {
	Outcome         string
	FailurePhase    string
	FailedTool      string
	FailureReason   string
	DispatchStarted bool
}

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

type Sink func(delta string)

type StreamIdleInfo struct {
	Provider       string
	ModelID        string
	RoundElapsedMs int64
	IdleMs         int64
	PartialChars   int64
}

type ToolCallHandoff struct {
	AssistantText    string
	ToolCallDeltas   [][]openai.ChatCompletionChunkChoiceDeltaToolCall
	Report           *RoundReport
	UpstreamProvider string
}

type ToolCallHook func(ctx context.Context, h ToolCallHandoff) error

type ToolDispatcher interface {
	// Plan classifies each call on its own: prepared project-confined structured reads may
	// overlap within a contiguous run, and every other call is a serial barrier that keeps
	// model-call order across the runs on either side of it.
	Plan(calls []AssembledToolCall, maxConcurrency int) ToolPlan
	// Dispatch executes one authorized-or-denied call and returns its tool-result
	// content. A denied call returns the deny envelope as the content with a nil
	// error and ToolResult.Denied set; the loop persists that envelope and its
	// denied_by decides what happens next — a user or unclassifiable denial halts
	// the turn, a recoverable one (permissions.IsRecoverableDeniedBy) re-issues (see ToolResult).
	// A non-nil error is an internal failure that aborts the loop without partial
	// continuation.
	Dispatch(ctx context.Context, call AssembledToolCall) (ToolResult, error)
}

type ToolLoop struct {

	// Expire fires the time limit immediately while Run has a deadline set; only tests call it.
	Expire func()
	// contains filtered or unexported fields
}

type ToolPlan struct {
	Units []PlannedToolCall
}

type ToolResult struct {
	Content  string
	Denied   bool
	Terminal bool
	WrapUp   bool
	Notice   string

	ModelContextImage string
	DisplayPatch      string

	// WriteTarget is the path a dispatcher resolved and authorized for an edit or create that
	// then returned exit status 0, and is empty otherwise. It is evidence of a successful
	// write, not a record of every filesystem change the call made.
	WriteTarget  string
	DeleteTarget string
	MoveTarget   MoveTarget
}