session

type Compaction interface {
	// AppendCompaction writes a compaction marker event. Compaction events are
	// self-describing: session backends trim their own in-memory history when
	// appending one, and message derivation always honors the latest marker.
	AppendCompaction(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data compaction.EventData) error
	AppendSummarizationRetryStart(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data RetryStartData) error
	AppendSummarizationRetryEnd(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data RetryEndData) error
	// IndexForCompaction rebuilds the model-visible message list with source
	// event seqs, including the latest compaction summary and retained tail.
	IndexForCompaction(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID) ([]compaction.IndexedMessage, error)
}

type ContextData struct {
	Cwd   string `json:"cwd"`
	Epoch string `json:"epoch"`
}

type Conversation interface {
	// AppendMessage sanitizes and appends a user/assistant message event.
	AppendMessage(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, typ agentkit.EventType, msg agentkit.ModelMessage) error
	// AppendToolCall sanitizes and appends a tool call event.
	AppendToolCall(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, call agentkit.ToolCall) error
	// AppendToolResult appends a tool result event.
	AppendToolResult(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, result agentkit.ToolResult) error
	AppendTurnStart(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID) error
	AppendTurnEnd(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data TurnEndData) error
	AppendStepStart(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, step int) error
	AppendStepEnd(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, step int) error
}

type Events interface {
	Conversation
	RunLog
	Compaction
	Skills
	// Recovery markers: overflow and generic auto-retry bracketing. No plugin
	// consumes these today; runtime records them through the same instance.
	AppendAutoRetryStart(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data RetryStartData) error
	AppendAutoRetryEnd(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data RetryEndData) error
	AppendOverflowRecovery(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data OverflowRecoveryData) error
}

type OverflowRecoveryData struct {
	Applied int    `json:"applied"`
	Reason  string `json:"reason,omitempty"`
	Error   string `json:"error,omitempty"`
}

type RecoveryData struct {
	TurnStartSeq  agentkit.EventSeq `json:"turnStartSeq"`
	Steps         int               `json:"steps"`
	OrphanResults int               `json:"orphanResults"`
	ClosedStep    int               `json:"closedStep"`
	Reason        string            `json:"reason"`
}

type RetryEndData struct {
	Success    bool   `json:"success"`
	Attempt    int    `json:"attempt"`
	FinalError string `json:"finalError,omitempty"`
}

type RetryStartData struct {
	Attempt      int    `json:"attempt"`
	MaxAttempts  int    `json:"maxAttempts"`
	DelayMs      int    `json:"delayMs"`
	ErrorMessage string `json:"errorMessage"`
}

type RunFinishData struct {
	Status  string `json:"status"`
	Summary string `json:"summary,omitempty"`
}

type RunLog interface {
	AppendTodoUpdate(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, items []Todo) error
	AppendRunFinish(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data RunFinishData) error
	AppendTurnContinue(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data TurnContinueData) error
	AppendUsage(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, data UsageData) error
}

type RunState struct {
	StartSeq agentkit.EventSeq
	Todos    []Todo
	Pending  []Todo
	Finish   *RunFinishData
	Repeats  int
	Usage    UsageData
	Context  int
}

type Skills interface {
	// RenderSkillContent formats loaded skill instructions for the model (tool result and event payload).
	RenderSkillContent(content skill.Content) string
	// AppendSkillLoad persists skill/load and returns the same rendered text.
	AppendSkillLoad(ctx context.Context, s agentkit.Session, agentID agentkit.AgentID, content skill.Content) (string, error)
}

type StepEndData struct {
	Step int `json:"step"`
}

type StepStartData struct {
	Step int `json:"step"`
}

type Todo struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Status string `json:"status"`
}

type TodoUpdateData struct {
	Items []Todo `json:"items"`
}

type TurnContinueData struct {
	Segment  int                     `json:"segment"`
	Reason   string                  `json:"reason"`
	Steps    int                     `json:"steps"`
	Messages []agentkit.ModelMessage `json:"messages,omitempty"`
}

type TurnEndData struct {
	Steps      int    `json:"steps"`
	StopReason string `json:"stopReason,omitempty"`
	StepLimit  int    `json:"stepLimit,omitempty"`
	Cancelled  bool   `json:"cancelled,omitempty"`
	Failed     bool   `json:"failed,omitempty"`
	// Message carries the turn's final assistant message when one was produced.
	// It lets consumers render the reply without depending on streaming deltas
	// (message/update) having all arrived.
	Message json.RawMessage `json:"message,omitempty"`
}

type TurnStartData struct{}

type TurnSteerData struct {
	// Outcome is always SteerOutcomeQueued today. Reserved as the seam for agents
	// that can report a finer result for their steering (injected mid-turn vs
	// deferred to the next turn) without a wire change.
	Outcome string `json:"outcome"`
	// SessionID is the conversation the running turn belongs to.
	SessionID string `json:"sessionId,omitempty"`
	// AgentID is the agent handling the running turn.
	AgentID string `json:"agentId,omitempty"`
	// UserID identifies the sender whose message was steered.
	UserID string `json:"userId,omitempty"`
	// Preview is a bounded, human-readable excerpt of the steered message.
	Preview string `json:"preview,omitempty"`
}

type UsageData struct {
	InputTokens  int `json:"inputTokens"`
	OutputTokens int `json:"outputTokens"`
	TotalTokens  int `json:"totalTokens"`
}