agui

type BoundaryTimestampSetter interface {
	SetNextBoundaryTimestamp(ts int64)
}

type EventHandler interface {
	MessageHandler
	ThoughtHandler
	ToolCallHandler
	TokenUsageHandler
	OnError(err error)
}

type MessageHandler interface {
	OnMessageStart() error
	OnMessageDelta(content string) error
	OnMessageEnd() error
	// LastMessageID returns the ID assigned to the current message by the
	// most recent OnMessageStart or OnThoughtStart call. Implementations
	// that do not generate IDs (e.g. CLI) may return "".
	LastMessageID() string
}

type PromptUsage struct {
	InputTokens       int64
	OutputTokens      int64
	TotalTokens       int64
	CachedReadTokens  *int64
	CachedWriteTokens *int64
	ThoughtTokens     *int64
}

type PromptUsageHandler interface {
	OnPromptUsage(PromptUsage) error
}

type ThoughtHandler interface {
	OnThoughtStart() error
	OnThoughtDelta(content string) error
	OnThoughtEnd() error
}

type TokenUsageHandler interface {
	// OnTokenUsage reports the current context-window occupancy. estimated is
	// false when the Agent CLI supplied the value and true when Quartet's local
	// tokenizer produced the fallback.
	OnTokenUsage(totalTokens int, estimated bool) error
}

type ToolCallHandler interface {
	OnToolCallStart(id, name string) error
	// OnToolCallArgs delivers either an incremental argument fragment or a
	// complete argument snapshot. replace=true means consumers must replace
	// the arguments collected for this tool call instead of appending args.
	OnToolCallArgs(id, args string, replace bool) error
	// OnToolCallResult delivers the tool call's terminal content. success
	// is false when the tool reported a failure status; the content passed
	// here matches what is written to disk (failed results carry the
	// "[failed] " prefix), so live-stream and history-reload renderings
	// stay in sync.
	OnToolCallResult(id, content string, success bool) error
	// OnToolCallEnd closes the tool call bubble. success mirrors the flag
	// that was passed to OnToolCallResult for the same id.
	OnToolCallEnd(id string, success bool) error
	// OnToolCallInterrupted closes the tool call bubble when the
	// surrounding run was cancelled / interrupted / superseded and the
	// tool never received a real terminal status. The UI renders this
	// as a "placeholder" state distinct from Success / Error so it
	// matches what history reload shows. reason is a short tag (e.g.
	// "interrupted" / "superseded") surfaced to the user.
	OnToolCallInterrupted(id string, reason string) error
	// OnToolCallStitched rewrites a previously-placeholdered tool bubble
	// with its real terminal payload after a late terminal arrived for
	// an eagerly-flushed (superseded) tool call. content matches what is
	// written to disk (failed results carry the "[failed] " prefix);
	// success is the real terminal status. supersededAgoMs is the gap
	// between the eager flush and the late terminal — passed through to
	// observability so operators can spot upstream stalls vs short race
	// windows. The handler is expected to override the live UI's
	// "Placeholder / Finished" state, unlike OnToolCallResult /
	// OnToolCallEnd which are not allowed to update finished bubbles.
	OnToolCallStitched(id string, content string, success bool, supersededAgoMs int64) error
}