contextmgr

type ContextManager interface {
	// InitNew creates a new conversation and returns its ID.
	InitNew(context.Context) common.ContextUID

	// NewContextUID generates a new unique conversation ID.
	NewContextUID(context.Context) common.ContextUID

	// Append adds a message to the conversation history.
	Append(context.Context, common.ContextUID, *schema.AgenticMessage) error

	// GetAll retrieves all messages in the conversation.
	GetAll(context.Context, common.ContextUID) []*schema.AgenticMessage

	// Len returns the number of messages in the conversation.
	Len(context.Context, common.ContextUID) int

	// Reset replaces the committed conversation history (useful for
	// compression). It must not remove pending messages.
	Reset(context.Context, common.ContextUID, []*schema.AgenticMessage)

	// EnqueuePendingMessages atomically adds user messages to the conversation's
	// pending inbox. The messages are not visible through GetAll until a
	// CommitTurn applies them. Implementations must preserve batch order.
	EnqueuePendingMessages(context.Context, common.ContextUID, []*schema.AgenticMessage) error

	// CommitTurn atomically appends turnMessages to committed history, then moves
	// every currently pending message to history immediately after that turn.
	// Calling CommitTurn with no turn messages flushes the current inbox.
	CommitTurn(context.Context, common.ContextUID, []*schema.AgenticMessage) (*TurnCommitResult, error)

	// CommitFinal atomically appends a final assistant answer and discards every
	// currently pending message. Subsequent EnqueuePendingMessages calls fail
	// until a new user message is appended by the next Do call.
	CommitFinal(context.Context, common.ContextUID, *schema.AgenticMessage) error

	// Delete removes a conversation and all of its pending messages.
	Delete(context.Context, common.ContextUID) error
}

type TurnCommitResult struct {
	AppliedPendingMessages []*schema.AgenticMessage
}